One of Flare 2016 r2's new, great features: Build Events

Disclaimer: This article is no way related to my employer, and is completely my own opinion. I'm not employed or sponsored by MadCap, I just really like the software.

Today I was able to get into and start playing with Flare 2016 r2, MadCap Software's most recent update to the long-running MadCap Flare line of technical documentation software.

Meandering through the new product, I stumbled on a new tab on the settings for my HTML5 target: Build Events.

My reaction follows:

So, here's the thing. Flare is already a great, dynamic piece of software. It's pretty much one script editor away from being a fully-featured IDE for web design and layout. One thing the software has always lacked, though, is a friendly way to automate (there are more technical ways, google "madcap flare api").

Implementing build events is manna from MadCap -- a quick, convenient way to trigger scripts before and after you start a build. It includes built-in variables that you can deliver to your scripts, including:

• The target name
• The project name (specifically, .flprj file, including extension)
• The project directory
• The output directory (for that target)

The example that MadCap includes in their documentation demonstrates executing a .bat script (a batch file for executing commands via the Windows command line interpreter -- you may recognize its interface as the Command Prompt), simply by including a path to the script:

I use AutoHotkey for my Window scripting, so I was immediately curious to see if Flare 2016 r2 will execute .ahk scripts.

I was next curious to see how it executes the script. For example, can I deliver the Flare build variables as command line parameters to my script?

It looks like spaces are the enemies. My path contains a space, which caused the parameter to be delivered in pieces. I tried a couple of the standard things, like wrapping the parameter in quotation marks, but I wasn't able to get it to quite work right. I tried the same thing with a batch script:

You can see that the parameters echoed into the text file correctly. I played around with syntax for delivering parameters to my .ahk script, and landed on the following working successfully:

Note the weird way I had to apply quotation marks to preserve the paths that included spaces. My guess is that when Flare executes the script, it's already wrapping the whole command in quotation marks (notice in the previous screenshot that I HAD to leave the last, closing quotation mark off), and AutoHotkey's parser isn't having it. The Windows command line wouldn't care as much as long as the parameters were appropriately wrapped, and indeed might require the whole line being executed to be wrapped in quotation marks. The fact that you can enter commands directly into the Pre-Build Event Command box...

...tells me that it's probably delivering that content directly into an instance of conhost to execute. So my .ahk parameters are probably getting screwed up because the command actually being executed is something like "C:\Users\mwilliams\Documents\Scripts\Flare2016r2\example.ahk "$(TargetName)" "$(ProjectName)" "$(ProjectDirectory)" "$(OutputDirectory)"", which Windows would be totally cool with, but AHK would not dig. There's probably some clever other ways you could try to work around this, like escaping the closing quotation mark to fool with the syntax more.

A pitfall with pre-build events is that the build process by default does not stop while the script executes. Because of this, you can't really take any actions on the files and folders being handled by the build because it'll already be off and away, building the files. If you want to ensure that the build waits while a script executes, you need to include the following:

Prepending start /wait to a line that executes a script will ensure that the build process is paused while your script executes.

There's no doubt that the being able to trigger scripts and events during your build is invaluable. The possibilities for ways you'll be able to interact with your content will be pretty much limitless.

Think being able to execute an analysis of content before and after, looking for things like broken links, missing images, etc. and then comparing results.

Think proofing and making global formatting changes to output after its built.

Think a vastly more dynamic build process, being able to move or copy subsections of content to other locations, or kick off additional builds. You could have a post-build script that executes the build of another target!

Excitingly, the pre- and post-build events also execute when you generate a project using madbuild.exe directly, meaning if you already have existing events or scripts that trigger builds via the executable, you can use madbuild to kick off additional scripts that you may want to act on the build, rather than having to account for executing them on your end at some point during the process.

Just a little proof-of-concept topic modification executed using pre- and post-build events:

Awesome stuff, and just one of the new features in MadCap 2016 r2.

Matt Williams is a technical writer at Tenable Network Security, Inc. He is a gigantic Flare nerd that specializes in custom solutions and automation for Flare-driven documentation workflows, as well as the front-end design and development of Flare skins and layouts. When he's not trying to break Flare in new and exciting ways, he's probably playing games with his wife and daughter while being buried under too many cats. And a dog. Find him on the MadCap Software forums as MattyQ.