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.
- There are OS X and Linux equivalents to these, but not to Flare, which is why I’ve limited this to Windows. [↩]