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:
- 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!
- Launch the Find and Replace panel by selecting Edit > Find and Replace > Find and Replace from the menu bar, or just press Ctrl + F.
- 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).
- Click the Start button to locate the first instance of the text.
- 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.
- Select the MyVariables set and then the variable you’ll be using to replace this particular text with. Click the OK button.
- 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).
- 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.
- 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.