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 (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.
2 answers
I'm pretty sure that the answer at the technical level is no. But this is really a question that needs to be addressed another level up.
The thing about structured writing is that it factors out certain aspects of the final publication, which then have to be factored back in by algorithms when it comes time to publish. The reason for factoring these things out is so that you can apply different algorithms to produce different kinds of outputs.
Different structured writing systems factor out different elements of a publication, and thus support different types of algorithms for producing different types of content.
The thing is, for the algorithms to work reliably, the writers have to get the structures correct. An editor with a fixed format like Word, FrameMaker, of Flare bakes the structures of those languages, and their representation, into the GUI. The GUI is based on the structures of those languages, and it will not fit other languages that have different structures.
DocBook and DITA, therefore, require different interfaces that expose their structures to the writer. Adopting a different language means adopting a different interface.
That said, DITA and DocBook are big complicated languages. You can build interfaces for them that only support a small portion of the structures that the full languages support. These may be easier to use, but they don't support all the features of the language. You can think of these interfaces as being related to DITA and DocBook the way MarkDown is related to HTML. Markdown is much easier to write than HTML, but it does not support more than a fraction of the HTML language.
Almost any writing formats in existence can be converted to DocBook. The result will be a valid DocBook document, but it won't take advantage of all the features of DocBook. Converting other formats to DITA is harder because of the topic architecture. But even where it works and produces a valid DITA file, it will not take advantage of all the features of DITA. Flare content could probably be converted to either DocBook or DITA, but the content would only contain those structures that are supported by the Flare interface. You would not get the full capability of Flare or DITA.
The point is, both DITA and DocBook support creating content structures that can be manipulates with a range of algorithms. But if your tool does not support the creation of the structures that those algorithms require, you won't be able to run them successfully, even if your source file is technically in DITA or DocBook.
In other words, you have to work back from the algorithms you want to run on your content. The algorithms you want to run require certain content structures to run reliably. So you have to choose a language that supports those structures, and then you have to choose a tool that lets authors create those structures clearly and easily.
If the tool you are using now does not support the algorithms you want to run, chances are it will not support the creation of the structures you need to run those algorithms. You need a tool that fits the format that supports the algorithms you want to run.
0 comment threads
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.
This post was sourced from https://writers.stackexchange.com/a/26745. It is licensed under CC BY-SA 3.0.
0 comment threads
0 comment threads