Flare file types

Flare file types

I posted today to the TECHWR-L list in response to a question about the types of files in Flare. There seems to be some confusion about whether or not Flare uses XML or XHTML or HTML files. The short answer is “yes.”

Here’s the long answer.

When we talk about file types in Flare, health there are really three different types of files:

  • The topic source files (where you edit your topics).
  • The supporting source files (where you edit things like alias files, viagra CSH links, glossary terms, page layouts, etc.).
  • The compiled help topics (that you copy to your production server, after you build your output).

First, let’s talk about what XML files are, and then we’ll describe each of the above categories.

XML is, (very) simply speaking, the parent language of all markup languages. Anybody can make a “flavor” of XML by defining which tags are allowed in their version of the language. A DTD or schema is a document that says which tags are allowed and/or required, and what order those tags have to appear in (if order is important).

So, a completely valid XML markup language could be the following:

<chapter title=”Under the Sun”>
Lorem Ipsum dolem or whatever.

Even people who know very little about HTML will know that you don’t have a <book> element in HTML. But you can create a valid XML-based language where <book> is a totally valid element, and any XML editor will allow you to create more <book> elements, even if the XML editor doesn’t know how to render the <book> element.

That is why people say HTML is one type of an XML-based language. There are valid tags:

, and there are invalid tags . HTML editors work because they know what each of the valid tags _do_.

Flare’s files use an XML-based markup language that is very similar to XHTML. We’ll talk about the differences in a minute.

Now, let’s look at each of the types of files I identified above.

First, topic source files. These files are based on Flare’s own XML-based language. This language, as I just said, is very similar to XHTML, but there are several key differences. For example, if you want to include a cross-reference in your topic, or a drop-down hotspot, those require tags that aren’t part of valid XHTML. So MadCap created their own XML language that allows you to do this. The files are still plain-text files; you can open them in any text editor or XML editor, and you will be able to see all the tags. And if you know a bit about Flare’s functionality, you can write the code yourself. You don’t have to use the Flare editor. In fact, if you just copy in pure XHTML code, it will render in Flare pefectly. You just won’t have the additions that Flare added to its own markup (like cross references, index entries, etc.).

The supporting source files in Flare (files that make the table of contents, the target definitions, glossaries, condition definitions, the page layouts, the master pages, the alias entries, the CSH-mapping, etc. etc.) are also in an XML format. These are NOT XHTML based, because they don’t function at all in a way XHTML was designed to work. Instead, these are based entirely on a MadCap created schema. If you understand the schema rules, you can also alter these by hand in a text editor or any XML editor. However, as with ALL XML-based files, you need to be careful, because if you make a change that the schema doesn’t understand, the file breaks. So while you CAN change these in a text editor, you usually will only edit these in Flare because Flare prevents you from messing up the structure of these files.

I think it is important to note that these supporting files are in an XML format, because it allows you to do several things. First, you can check your entire project into a source control system, and you can manage the files easily there. While you can obviously check binary files into source control, checking in text files (like these) makes history tracking, version tracking, and management much simpler, because you only store the diffs, not the entire source file every time you check the file in. Second, it gives you the flexibility to edit the source files in an external editor when you need to. I’ve used this ability on occasion to search through all the text files in the project to look for and replace a specific term (like a product name). I can check every file in the system for the name because every file is a text-based file I can open in Notepad (or whatever). I can even use a tool like TextPad and use regular expressions to make site-wide changes very easily.

One last note on items in this grouping: one type of supporting file MadCap uses is with it’s Capture tool. When you make edits or annotations to an image in Capture, the changes are stored in a .props file in the same folder as the image. That means that when you are doing site-wide find-and-replace, you can even find and replace image annotations in your screen shots. The next time you generate your output Capture generates new images based on the new data, and includes them in the Flare output. For translators, this means that you can translate all the text in screen shots without even needing to open a screen capture utility. You just translate the data in the .props file, and upon the next build, the translated text is now in the screen shot.

The last category I described above is topics in the compiled help system. In this case, I’m talking about WebHelp, since it doesn’t make any sense to talk about Word output file format in the context of this discussion. Your generated help files are HTML-based files with the supporting javascript files to do the whiz-bang DHTML-style effects. Items such as cross references or index entries (that are part of the XML that Flare recognizes) are still in your output, but since the HTML schema doesn’t recognize them and know how to display them, it ignores them. If you were to run Flare’s output through an HTML validator (a tool that compares the markup to the schema to see if all markup matches the schema), Flare’s output wouldn’t validate, because it includes those extra tags, but all modern visual browsers just ignore tags they don’t understand when they build the page. So, in effect, you have HTML output. (Honestly, I don’t know what screen reading software does with non-valid HTML tags, so I don’t know how Flare output works for visually impaired users who use a text-to-speech browser to navigate the web.)

Sorry for the novel. But as I read this thread, I realized that not everybody understands the terms we bandy about like “XML”, “XHTML” and “source files.” I hope this explanation shows that there really are three distinct types of files used by Flare, and I hope you can see how they are all technically “XML”, some are a modified “XHTML”, but all the output files function like “HTML” in the browser.

Clear as mud? Ask in the comments, and I’ll try to clarify any questions you have.

4 responses to “Flare file types”

  1. Hi Paul.. Not sure if you’ll see this, but I’m wondering how difficult it would be to convert a couple of hundred Confluence 3.3 pages to the latest Madcap Flare XML format. I think Confluence 3.3 uses Textile markup.

    • Converting the source files would be tough, but if you could save the HTML-rendered files, you should be able to import those into Flare without too much trouble, if the page itself is clean.

      In the end, what I’d probably end up doing is copying the files from the COnfluence output and pasting them into Flare and applying formatting. THat is, unless you can make Confluence export something that Flare can easily import, like a Word doc or something.

  2. Two years later after you wrote this post, but I just wanted you to know that I found this incredibly helpful. I almost didn’t click on it because from the title, I thought it was a list of the file extensions that Flare uses. I am glad I did though.

    Before, I could clearly articulate how Flare uses HTML and CSS, but I felt more uncomfortable talking about how XML comes into play. This article was really articulate and clarified my own picture of how Flare works.

    Anyway, just dropped in to say thanks! 🙂

  3. Hi Paul,

    Great article Paul.

    I am a relative newbie to Flare. Our customers want structured XML output which can be integrated into their own apps. From your article, I believe this is not possible at present. Am I correct? We use Flare 11 to publish protocol specs. It seems a bit much but that’s the source vendor format, which we then customize at our end before sending out as PDFs to our customers.

    Can we generate XML output that can be consumed for reuse by ISVs?

Leave a Reply