Creating Flare Debug Outputs

Introduction

MadCap Flare does a great job combining all the different underlying single-source authoring bits and pieces —as well as standard HTML components— so they are seamlessly rendered in the resulting output.

There are times, however, when it is helpful to highlight those underlying elements in the resulting output — Making them stand out can support the review process, help identify potential issues, and clarify how the content is being assembled.

These guidelines describe a simple approach to tweak Flare projects so that specific outputs can be produced where those elements are highlighted.

Jump Start

Those who prefer to cut to the chase can review the Disclaimer section and then fast-forward right to the Implementation Cheat Sheet.

Intended Audience

The guidelines presented here are intended for Flare users. These techniques were crafted with Flare localized outputs testing and troubleshooting in mind, but content creation teams may also avail of them.

Such techniques are straightforward, but they do require certain knowledge of Cascading Style Sheet editing and Regular Expression procedures. As such, software programmers and engineers would be the most likely candidates to implement them.

Authors, project managers (in both, authoring and localization roles), translators, and proofreaders dealing with Flare projects might find this material useful, particularly when formulating precise requests for a colleague or team member who can implement the described tweaks.

Initial Considerations

As in any software development process, better safe than sorry is the recommend principle to go by.

The guidelines described in this document have been tested and generally work as expected, but caution is paramount to safeguard the production Flare project. Creating backups or, when using source control, following established best practices is strongly recommended.

Since the goal of creating a debug version is to fix potential issues, it is advisable to plan ahead for the subsequent correction steps. Among other decisions, the plan should determine whether the fixes validated in the debug version will be replicated in the production version or whether the debug version itself will eventually become the new production version.

Although Regular Expressions are not ideal for parsing HTML code, they can still be used effectively to achieve the intended results with a high degree of reliability. For simplicity and convenience, this guide uses Flare’s own Find and Replace feature to illustrate the search and replace in files procedures, although any text editor or development tool that supports similar functionality may be used.

Overview

In software development parlance, defects are known as bugs, so debugging is the process of identifying and resolving them.

To support this process, software developers usually create a special version or debug build that includes particular features aimed at streamlining the debugging process. For example, an application may include more detailed and code-related data in any error message meant for testers and programmers, or a video game may display the audio filenames being played on-screen in order to assess whether any of them is incorrect — To some extent, these debugging techniques can be applied to Flare outputs.

Once a Flare project debug version is implemented, certain elements in the output will visually stand out from the rest. Their appearance will vary depending on the type of underlying component they stem from, as illustrated in the following example:

When creating a debug output, the basic idea is to implement style classes and supporting tags to the intended single-source authoring elements and other regular HTML tags. Such elements covered in this document are:

• Project-wide Variables
• Target Overriding Variables
• Snippets
• Filenames
• Hard-Coded Page Breaks
• Images
• Conditional Text
• Conditional attributes

Flare and CAT tools

Translations from one language to another are typically carried out using dedicated software applications known generically as Computer-Assisted Translation (CAT) tools.

These applications extract the translatable content from the underlying files, such as topics and snippets, and present it as plain text combined with interspersed placeholders that represent HTML and single-source elements. For instance, this is how a translator would see the above example in a CAT tool:

To add further complexity, the actual content in single-source elements may vary depending on certain criteria defined at design time known as conditions in Flare terminology. When translated, the plain text must be accurately adapted to the single-source element contents it refers to.

As it is plain to understand, this challenging black-box-like constraint makes translation errors more likely and, by and large, they are mostly detected in the output. Such likelihood adds up to the difficulty to assess and, consequently, to fix those errors spotted in regular, immaculate text outputs, with no visible clues indicating what is going on under the hood.

Implementation Cheat Sheet

The process to create a debug output can be summarized in three main stages:

• Download or create the debug CSS file
• Link the above CSS file to the relevant existing CSS file or files
• Implement the required supporting tags

These stages are further discussed in the following sections.