Wednesday, November 27, 2019

Single Sourcing with MadCap Flare – Part 5 – Other Features


My previous posts discussed the conditionality, placeholder, and project import features that provide so much single-sourcing power. In this post, I’ll discuss several lesser-known ones and one new one.

Conditionalized Styles

Most projects use one stylesheet but there are options. For example, you can create two stylesheets for use in a project and specify that stylesheet A should be used for online targets and B for print. The more efficient approach is to create one stylesheet and allow for stylistic variations in the targets by using the medium feature. Still another approach is to create one stylesheet and use the mc-conditions property in the Stylesheet Editor to literally turn a particular style on or off depending on the target.

You can find the mc-conditions property in the Unclassified property group if you’re looking at the styles by group, or alphabetically if you switch to the alphabetic listing.

CSS Variables

There may be cases where you want to apply the same property value to multiple styles. Consider color; you’d specify the same color for h1, h2, and h3. However, having to repeatedly specify the color makes it easy to make a mistake – typing the wrong digit in a hex-value color specification, for example. One solution is to specify the color in the body style, which propagates it down to the subsidiary styles, but this might still be a problem if you had to specify alternative colors for h4, h5, and h6. The CSS variables feature eliminates this problem by letting you specify the color in one variable and use that variable in different styles.

There are several steps involved in working with CSS variables – none complicated but detailed enough that I’ll recommend that you look at the CSS Variables topic in the Flare help.

Clean XHTML Target

We typically use Flare’s topic editor to create content for Flare targets but it also lets us create content – HTML files – for use outside Flare, in a wiki for example. However, external programs may trip over the MadCap-proprietary features. To deal with this, MadCap added the Clean XHTML target. Selecting this target generates the output using standard XHTML but strips out the MadCap-specific features. It’s not a widely-used feature, at least in my experience, but it does let authors add support for other programs without having to bring another tool into the picture.

Easy-Sync

It’s common for authors to have to import Word or FrameMaker files into Flare, converting them into topics in the process. The import can be a one-time task, after which edits are done by the Flare author in Flare. Alternatively, we may want the original author, who probably does not have Flare, to be able to continue to update the imported files in the original tool and have those change automatically flow into the Flare topics. The latter option is the basis for the Easy-Sync feature.

This feature is driven by two options on the Word or FrameMaker Import editor. Prior to version 2019 r2, we used the “Link generated files to source files” option on the first tab and the “Auto-reimport before generate output” option on the Options tab. (In Flare 2019 r2, these two options are combined in the Reimport group at the bottom of the Advanced Options tab.)

The Link option creates a link from the Flare project to the original Word or FrameMaker files. The Auto-reimport option tells Flare to compare the content from the previous import with the content in the files now. If they differ, Flare automatically reimport the Word or FrameMaker files, creating new topics and overwriting the topics from the previous import.

Easy-Sync lets us create nearly-automated publishing workflows. We create and maintain the content in Word or FrameMaker and use Flare as the publishing engine. The problem is that this feature overwrites the topics created by the previous import. For example, if we import a Word or FrameMaker file into Flare, breaking it up into topics in the process, and then add Flare features like links, those Flare features will be lost. So Easy-Sync is useful but it calls for careful project planning and management.

Responsiveness

One change affecting tech comm is the need to generate output to run on different devices – generally desktops, tablets, and phones. The output’s look may have to differ between the devices, and MadCap has been adding support for this with Flare’s responsive output and responsive layout features. (I gave a two-hour workshop on these features at MadWorld 2018.) Flare 2019 r2 adds a new feature in support of responsiveness, responsive conditions.

The responsive conditions feature adds responsiveness to conditions (sorry…). In prior versions of Flare, conditions were simply set to be included or excluded. The new responsiveness feature lets us specify that material be included or excluded depending on the output device. For example, we might use one graphic for a target aimed at desktop monitors but one with larger text for target aimed at phones. Or, my favorite example, automatically change the wording in a command from “Click the button” to “Tap the button” when generating output for a tablet or phone.

There are several steps to working with the responsive conditions feature, again none complicated but detailed enough that I’ll recommend that you look at the Responsive Conditions – Set By Media Query link in the What’s New section of the Flare 2019r2 help.

Summary

I hope these posts have given a sense of the range and power of the features that Flare offers for single-sourcing. Technically, they work well – the older features almost flawlessly after having gone through their birth pangs. The common problem with the features is managing them. That will be the subject of the last post in this series.