Batch File Output in MadCap Flare

I have a couple of products which I document using MadCap Flare to generate about two dozen help files and another half-dozen PDFs. These outputs are spread across multiple Flare projects which I inherited. Producing a full set of output for a release can prove to be nearly a full day’s worth of effort so I finally got around to creating a single Windows batch file to take use of the command line interface for Flare. Flare has had the command line feature for a few years now, but regrettably, I just never took the time to learn it. It’s actually very simple to implement, even if you’re not that familiar with writing batch files or the idea of the command line scares you off a bit.

Tools Used

First, I should point out that to further streamline my work, I’ve implemented a couple of other tools besides just Flare. These are all free, open-source tools which I highly recommend you having in your tech-writer toolkit1.

  • 7-Zip – The best compression utility out there. The command line interface is easy to wrap a lot of files into a compressed archive (variety of formats, including .zip).
  • NcFTP – A very easy-to-use FTP which has some command line utilities capable of transfer in passive mode (required for our FTP behind a firewall).
  • Notepad++ – A great text editor which has syntax highlighting for batch files.

And of course Flare. However, you could also easily integrate much of the same workflow into using the DITA Open Toolkit as well as any other help authoring tool with a command line interface.

Set Up

I prefer to use dates in my archive file names just to make things clear for the teams downloading them what ‘version’ it is. Sure, we could just check timestamps, but this just makes it more obvious. I use the international data format — YYYY-MM-DD — as the prefix for my titles and I wanted this automated into my batch file. However, as my region is US on my Windows machine, I need to just change the short date format in the Control Panel to this format. That way, I can use the %date% environment variable to always input the current date when the archive is created.

Aside from that, installing the above tools is all that is required.

Creating the Batch File

Notepad++ can be used to create and edit the Batch file. Simply create a new document and save it (somewhere convenient) with the .bat file extension. This also indicates the file type to Notepad++ so the syntax is highlighted appropriately (simply makes editing easier).

I want to place my outputs in a Zip archive for the convenience of labeling them all with the current date and placing onto a FTP server for other teams to download. So I set a variable to include the current date:

set ZipOut=C:\Documentation\Output\%date%_my_files.zip
echo %ZipOut%

(The second line just outputs the same back to me so I can verify the date string was as intended)

Next, I change the directory to the MadCap Flare installation:

cd\Program Files (x86)\MadCap Software\MadCap Flare V8\Flare.app

Then I can use the command line entry — madbuild — to initiate builds of any number of Flare projects and targets (which are individual outputs from a single-source Flare project).

madbuild -project "C:\Documentation\Product\ProductHelp_A\Product_A.flprj" -log true -target "Product_A HTML Help"
madbuild -project "C:\Documentation\Product\ProductHelp_B\Product_B.flprj" -log true -target "Product_B HTML Help"
madbuild -project "C:\Documentation\Product\ProductHelp_C\Product_C.flprj" -log true -target "Product_C HTML Help"

Next, I want these three compiled HTML Help files to get placed into the ZIP file I named in my variable. This uses the command line interface for 7-Zip:

cd\Program Files\7-Zip
7z a -tzip %ZipOut% @C:\Documentation\Output\Product_file_list.txt

Where Product_file_list.txt is just a plain text file containing the absolute file path and file name of each of the compiled HTML Help files. It’s described in detail in the 7-Zip help, but essentially the entire file path for each file to be included is on a line in the text file. No special syntax or separators required.

Lastly, I want to transfer the ZIP file over FTP to a convenient place for the rest of the team. The default Windows FTP program cannot run in passive mode, which is required to navigate a firewall. However, the Linux FTP client NcFTP has been ported to Windows and has a command line interface which is more flexible.

cd\Windows
ncftpput -F -u username -p password ftp.mydomain.com /Product/ %ZipOut%

Running the Batch File

Just save the file in your text editor. All that is needed to run it is to simply double-click the .bat file in Windows Explorer. The command line window will open, execute each line in order, and close upon completion.

It would be easy to also use Windows to schedule running the same thing nightly or weekly if you need to regularly post updates of your work.

  1. There are OS X and Linux equivalents to these, but not to Flare, which is why I’ve limited this to Windows.

Using Variables with Find/Replace in Flare

This one is a pretty simple trick and, to be honest, one that a lot of folks probably figured out sooner than I did. With just a little bit of work, you can easily replace oft-used words or phrases in your Flare project with a variable. This is especially useful if you find yourself writing early on in the development process where some terminology of features or a product interface are subject to change.

Or, if you’re like me and you just don’t know what the hell such-and-such thing is called and the development team has yet to answer your e-mail asking because they’re too busy forwarding it to everyone else in the company who’ll get a good laugh out of the ridiculously silly question. Okay, that hasn’t actually happened (except for the part about me not knowing what something is actually called). At least not that I’m aware of.

So, here are the steps for finding all the instances of a term and replacing it with a variable:

  1. Create a Variable in the MyVarables set.

    Note: It’s good practice to use camel notation when naming your variable. Keep it short, but make it something you can easily identify (variables don’t have dental records and teeth and such in the event of a serious accident). And be consistent in how you name things!

  2. Launch the Find and Replace panel by selecting Edit > Find and Replace > Find and Replace from the menu bar, or just press Ctrl + F.
  3. Enter the text you wish to substitute with a your new variable in the Find What field. Under the options section, select (whole project) for the Find In: field, Topics for File Types, and make sure the option for Find in source code is cleared (though we’ll use that option in a moment).
  4. Click the Start button to locate the first instance of the text.
  5. The searched-for text will be selected for you in the XML editor within a topic file. Click the topic’s tab along the editor window just to make that part of the program window active. Now, select Insert > Variable… from the menu bar to open the Variables dialog.
  6. Select the MyVariables set and then the variable you’ll be using to replace this particular text with. Click the OK button.
  7. Now, you need to get the actual markup for this variable. The fastest way I know to do so is click the Locate in Content Explorer button in the Standard toolbar. Then, with the topic file now selected, right click and select Open With > Internal Text Editor. Now, hunt around until you locate the variable tag. It looks like this:

    <MadCap:variable name="MyVariables.SuchAndSuch" />

    Select and copy this entire tag.

    Note: You can also use the Send To menu button, also located on the standard toolbar. It’s the one that looks like an envelope and that you probably thought was just for e-mailing a file. However, it will actually open up the current file in an external program, including your handy text editor (I use TextPad).

  8. Now, back in the Find and Replace panel, this is what you’ll paste into the Replace with: field. But now you’re going to make sure that the Find in source code option is now selected.
  9. Click the Start button again (you changed the options since you last did so). Use the Replace and Find Next buttons to swap out the text with the variable markup one by one.

A Note of Caution

You’re going to be replacing text in the source markup here so be careful. I strongly urge you to not use the Replace In All Files button. It’s fast but it’s also risky. You’ll replace any instance of the text; anywhere: keywords, etc. You might find yourself putting a variable tag where it really doesn’t belong. Fortunately, Flare will likely just give you a gentle scolding and ignore your silly little nonsense. But, you might just find a loophole you wish you hadn’t. It’s best to do this one-at-a-time, even if that takes a while.

Ideally, MadCap would add an option in the the Replace With field to just select one of your variables from there. This way, you don’t have to Find/Replace in source code and run the risk of doing something unintended (hopefully they’d handle all that under the hood). But until then, only replace what you are sure is content material and not anything else.

Extend This Trick

Now, you can also use this little trick for finding and replacing other code, so you could add a particular style to any instance of a phrase. Ex: replace "OK button" with "<strong>OK</strong> button". I’ve yet to find a limit to the number of characters available in the Find and Replace field, but I suspect it’s probably around 256 or so. I don’t think you’ll be replacing A Tale of Two Cities with War and Peace using this.

Further, you can use regular expression for — well — anything that you just about think of, I suppose. You can also use wildcards which though not as sexy as RegEx are still quite useful when just doing text search. If you’re just looking for any instance of noun — plural or singular; RegEx might be swatting flies with tanks.