Batch File Output in MadCap Flare

I have a cou­ple of prod­ucts which I doc­u­ment using Mad­Cap Flare to gen­er­ate about two dozen help files and anoth­er half-dozen PDFs. These out­puts are spread across mul­ti­ple Flare projects which I inher­it­ed. Pro­duc­ing a full set of out­put for a release can prove to be near­ly a full day’s worth of effort so I final­ly got around to cre­at­ing a sin­gle Win­dows batch file to take use of the com­mand line inter­face for Flare. Flare has had the com­mand line fea­ture for a few years now, but regret­tably, I just nev­er took the time to learn it. It’s actu­al­ly very sim­ple to imple­ment, even if you’re not that famil­iar with writ­ing batch files or the idea of the com­mand line scares you off a bit.

Tools Used

First, I should point out that to fur­ther stream­line my work, I’ve imple­ment­ed a cou­ple of oth­er tools besides just Flare. These are all free, open-source tools which I high­ly rec­om­mend you hav­ing in your tech-writer toolk­it1.

  • 7‑Zip — The best com­pres­sion util­i­ty out there. The com­mand line inter­face is easy to wrap a lot of files into a com­pressed archive (vari­ety of for­mats, includ­ing .zip).
  • NcFTP — A very easy-to-use FTP which has some com­mand line util­i­ties capa­ble of trans­fer in pas­sive mode (required for our FTP behind a firewall).
  • Notepad++ — A great text edi­tor which has syn­tax high­light­ing for batch files.

And of course Flare. How­ev­er, you could also eas­i­ly inte­grate much of the same work­flow into using the DITA Open Toolk­it as well as any oth­er help author­ing tool with a com­mand line interface.

Set Up

I pre­fer to use dates in my archive file names just to make things clear for the teams down­load­ing them what ‘ver­sion’ it is. Sure, we could just check time­stamps, but this just makes it more obvi­ous. I use the inter­na­tion­al data for­mat — YYYY-MM-DD — as the pre­fix for my titles and I want­ed this auto­mat­ed into my batch file. How­ev­er, as my region is US on my Win­dows machine, I need to just change the short date for­mat in the Con­trol Pan­el to this for­mat. That way, I can use the %date% envi­ron­ment vari­able to always input the cur­rent 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 cre­ate and edit the Batch file. Sim­ply cre­ate a new doc­u­ment and save it (some­where con­ve­nient) with the .bat file exten­sion. This also indi­cates the file type to Notepad++ so the syn­tax is high­light­ed appro­pri­ate­ly (sim­ply makes edit­ing easier).

I want to place my out­puts in a Zip archive for the con­ve­nience of label­ing them all with the cur­rent date and plac­ing onto a FTP serv­er for oth­er teams to down­load. So I set a vari­able to include the cur­rent date:

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

(The sec­ond line just out­puts the same back to me so I can ver­i­fy the date string was as intended)

Next, I change the direc­to­ry to the Mad­Cap Flare installation:

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

Then I can use the com­mand line entry — madbuild — to ini­ti­ate builds of any num­ber of Flare projects and tar­gets (which are indi­vid­ual out­puts from a sin­gle-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 com­piled HTML Help files to get placed into the ZIP file I named in my vari­able. This uses the com­mand line inter­face 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 con­tain­ing the absolute file path and file name of each of the com­piled HTML Help files. It’s described in detail in the 7‑Zip help, but essen­tial­ly the entire file path for each file to be includ­ed is on a line in the text file. No spe­cial syn­tax or sep­a­ra­tors required.

Last­ly, I want to trans­fer the ZIP file over FTP to a con­ve­nient place for the rest of the team. The default Win­dows FTP pro­gram can­not run in pas­sive mode, which is required to nav­i­gate a fire­wall. How­ev­er, the Lin­ux FTP client NcFTP has been port­ed to Win­dows and has a com­mand line inter­face 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 edi­tor. All that is need­ed to run it is to sim­ply dou­ble-click the .bat file in Win­dows Explor­er. The com­mand line win­dow will open, exe­cute each line in order, and close upon completion.

It would be easy to also use Win­dows to sched­ule run­ning the same thing night­ly or week­ly if you need to reg­u­lar­ly post updates of your work.

  1. There are OS X and Lin­ux equiv­a­lents to these, but not to Flare, which is why I’ve lim­it­ed this to Win­dows. []

By Jason Coleman

Structural engineer and technical content manager Bentley Systems by day. Geeky father and husband all the rest of time.

Leave a comment

Your email address will not be published. Required fields are marked *