Post History

Source: https://writers.stackexchange.com/q/25515
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

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,<sup>1</sup> 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".

<sup>1</sup> 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.

Original score: 1