Setting document variables before building as a batch target

[Msquared]

I'm about to automate my Flare target builds, and I'm looking for a simple way of editing my Flare target files before I run the build.

It's slightly more complicated than just using a Flare batch target, as everything is under source control and some of my topics are auto-generated from definitions in the code base. I also need to copy the Flare build outputs to their final location. We also have some PDF-only documents that are still generated from Word sources, so those PDFs are "built" by a straight copy from their existing location to their final location for the build. This means I need to wrap various commands around bits of the build to do things like checkouts, checkins, auto-generation of content, copying files etc, hence the need for a script. All this is under control . . .

However, things like the document date (print documents only), software version, copyright year etc are set as variables in the target, and these need to be updated immediately before the build, ideally with a value provided to me from our software build system. Can anyone suggest a simple way of doing this that can be included in my batch build script?

For example, I have a variable called DocumentDate, which I set by default in all my targets to [DD MMM YYYY]. For the final build, I'd like to set it to the a real value. For example, if the build was today, I'd like 30 July 2013.

So in the target file, or example, I’d need to replace:

Code: Select all

Name="GLOBAL DocumentVariables/DocumentDate">[DD MMM YYYY]</Variable>

With

Code: Select all

Name="GLOBAL DocumentVariables/DocumentDate">30 July 2013</Variable>

I can't believe I'm the only person who wants to do this, and I can't believe that the rest of you manually update the build date and other similar build-specific variables in each target immediately before each batch build. So I'm intrigued to know how others do this. Have I missed something obvious?

[NorthEast]

I think the short answer is no - Flare doesn't provide anything to automatically update variables from an external source.


However, do the variables change for each individual build, and do they need to?

- For a date stamp, you don't need to do this manually, just use the variable System > ShortDate.

- For the copyright year, presumably that doesn't change very often.

- For the software version, I use a variable which I need to update manually in the target for each public release (e.g. '1.4'). However, I don't include the detailed build number of the software itself from TFS (e.g. '1.4.2013.57') which would be different for each new software build. We don't really need the build number in the documentation as it's visible in the software itself.

If you wanted the software build number as variables in the documentation, then that's going to be tricky. You'd have to build the Flare targets as part of your software build process (e.g. using MadCap command line), and write code/script to automatically get the build number (e.g. from TFS) and use that to update the version variable(s) in the target file prior to running the Flare target builds.

[Msquared]

Thanks for confirming that I hadn't missed anything.

I know for published documents most of the values don't change "very often", but I am single sourcing multiple outputs for three different products, all from the same content, and one of the potential points of failure is remembering to update things like dates and versions as required. We do lots of maintenance releases too. At present, it's easy to auto-build the docs with the software, but someone needs to remember to update each of the targets for the few doc variables that may change. This also means that a technical author needs to be involved to do this manually. Everything else in the build can be automated, and hence produced as required by anyone who needs to do it.

I also don't like embedding "live" document dates and numbers in test versions of the documents which are build daily as part of our integration and test process. These things can and do get sent to customers by well-meaning developers by mistake. I'd rather have all my test documents emblazoned with "Draft for internal use only" (another target variable I'd like to set for each build - this one is blank for published docs).

I can (and will) of course, write a noddy script to update the target values outside of Flare as part of the doc build script I'm about to write. I'm just a bit surprised to be having to do it, and wanted to check I'd not missed something. That's all.

I guess what I'm getting at is the general principle that some variables are build time variables, non just target-specific variables, and for a truely useful batch build system, it would nice to be able to set them when the batch build is invoked. It's incidental that we may be able to work around some of them, and that others don't change very often.

[NorthEast]

If the variables are causing a headache, then perhaps look at what variables you actually need to include in the documentation, and if they're relevant to the end-user. Some of our help doesn't include any version information as it's never supplied separate to the software; but I can see it's required when you supply standalone docs like a PDF.

I guess the problem is that the variables you're talking about are external to Flare, so Flare doesn't know where to get them from. Perhaps MadCap would add integration options for standard tools like Visual Studio, so maybe put in a feature request for what you'd like to see.

[Msquared]

I guess the problem is that the variables you're talking about are external to Flare, so Flare doesn't know where to get them from.

That's exactly it! I know where to get them from. All I'd like is for Flare to provide a way to let me tell it about them. I will raise an enhancement request, since I don't think I'm unique in having a category of variables that I want to set/override at build time. I can see that anyone who only produces on-line outputs may not need to worry about dates and versions etc, but as you say, those of us who produce printed outputs as well may need to.