The Society for Technical Communication is an individual membership organization dedicated to advancing the arts and sciences of technical communication. It is the largest organization of its type in the world. Its 25,000 members include technical writers and editors, content developers, documentation specialists, technical illustrators, instructional designers, academics, information architects, usability and human factors professionals, visual designers, Web designers and developers, and translators - anyone whose work makes technical information available to those who need it.

The STC Toronto Chapter was founded in 1959 (then the Society of Technical Writers) and is the largest chapter in Canada.

About this Newsletter:

The Wandering Eye
FrameScript - Getting More Productive with FrameMaker
by Keith Soltys

One of the things I like the most about Microsoft Word is that you can use VBA to do just about anything, from automating repetitive tasks on up to creating custom dialog boxes and data entry forms. FrameMaker has no built-in scripting language, although if you are a decent C programmer, you can modify it with the Frame Development Kit (FDK). Fortunately, FrameScript provides an alternative to heavy-duty programming.

FrameScript runs as a FrameMaker plug-in, adding its own menu to FrameMaker. Out of the box (or more accurately, the download), you can run any of the twenty-odd sample scripts provided, or others that you can find on the net. However, its real utility comes when you start writing your own scripts.

Programming in FrameScript is about on a par with VBA programming, in terms of complexity. The FrameScript language itself is fairly straightforward, and if you've done any programming in VBA, Java, or a scripting language like PHP or Perl, you won't have much trouble with it. The tricky part is figuring out FrameMaker's object model, the code that lets you interact with the internals of documents. FrameMaker's object model is more complex than Word's, although it's more logical and better documented.

Most of the things that you can do with VBA in Word, you can do with FrameScript in FrameMaker.

• Repeat repetitive tasks: For example, I wrote a script to create a newlink marker for every heading in a document.
• Add preset options to existing Frame commands: For example, modify the Insert Anchored Frame command so that At Insertion Point becomes the default.
• Create new custom dialogs: The Change Paragraph Format sample script is a good example (and a very useful one too). Another is a script I wrote that lets me insert gotolink markers from a list of newlink markers in a document.
• Modify files: For example, save all files in a directory as PDF or MIF.

Framescript isn't perfect:

• Scripts installed via FrameScript's graphical interface are not persistent; that is, they stay installed only as long as you keep your FrameMaker session open. This drove me crazy until I figured it out. It cost me several hours of wasted time, as it isn't clearly documented.
• You are limited in your choice of keyboard shortcuts to run scripts; for example, CTRL+ALT combinations aren't supported by default. Rick Quatro has a script for sale that works around this limitation.
• The script editing window is pretty basic. You can work around this by using an external editor (I'm using TextPad), with a hook into FrameScript to run scripts. While this will give you syntax highlighting, there's no tag completion, like there is in VBA.
• Debugging is primitive; errors in scripts just get reported (usually with the offending line number) in the FrameMaker console. Klaus Mueller has a script that will analyse scripts and report some syntax errors.
• There's no macro recorder, which would let you run a series of commands in FrameMaker and spit out the FrameScript code to repeat those commands. This is a very useful feature of MS Word, which can save a lot of time in assembling macros, not to mention being a good learning tool.

FrameScript ships with several PDF documents.

• A User's Guide covers installation and customization of the program and installing scripts.
• Basics is an overview of writing scripts.
• FrameMaker Reference is a guide to the FrameMaker object model
• ESL Object Reference is a reference to the system objects that you can use to create custom dialog boxes and forms.

As reference material, the documentation is quite good. Certainly, the documentation of FrameMaker's object model is better than what you'll find in VBA for Word. However, it will not teach you how to write scripts. For that, I strongly recommend purchasing Rick Quatro's FrameScript: A Crash Course, which steps you through most of the techniques you'll encounter in using FrameScript. Although it was written for FrameScript 2, FrameScript 3 is backwards compatible, so the scripts in it still work. You can also study the sample scripts; however, not all of them are commented, a curious oversight in a product like this.

If you get FrameScript, you'll find the FrameScript mailing list an invaluable resource. I've learned a lot from following the discussions on the list and from the help that several people have given me. The list is hosted by Yahoo Groups, and the list's name is framescript-users.

FrameScript is a powerful tool that no serious FrameMaker user should be without. At a reasonable cost of $150 US, it's hard to come up with a better way of increasing your productivity in FrameMaker. Even if you don't want to write your own scripts, you can always purchase scripts or script bundles from people like Rick Quatro. A suggestion to Adobe: consider bundling FrameScript with FrameMaker, even if it's just a limited subset that can only run compiled scripts. This would really help to overcome some of FrameMaker's longstanding limitations.

Keith Soltys has been working as a technical writer for 16 years, and is currently at the Toronto Stock Exchange. He maintains the Internet Resources for Technical Communicators web site and has recently started a weblog. He lives in Pickering with his wife, two children, a cat, and an ever growing collection of Grateful Dead CDs.