Features

Write Your Own Tools

August 10, 2011

By Fred Wersan | Senior Member

Most technical writers have one or more high-powered programs such as Word or FrameMaker that do almost everything they need to do. When these programs miss significant functionality, software vendors step in with utilities and plug-ins to fill the gaps. Yet even with all of these resources available, none of the programs do everything we want them to do, nor do they do some things as well as we would like or in a way that fits our personal workflow. In this article, I will describe ways that you can write your own tools to save yourself time and effort and make your life easier.

The purpose of writing your own tools is to:

  • Automate repetitive, boring work procedures
  • Adapt applications to your workflow
  • Provide missing functionality

The idea is to let the computer do the mindless work so that you have more time to spend doing the thinking. In addition to improving your day-to-day writing experience, writing your own tools can extend your skills and improve your value to your employer and provide a sense of accomplishment.

In this article, I describe several ways that you can write increasingly complex tools to meet your writing needs. They are:

  • String replacement
  • Simple macros
  • Complex macros and Windows automation scripting
  • Application-level scripting

I will describe each approach and then present a progressively more complex example of how to solve a common writing problem. (As I progress, I will mention the programs that I use to write tools. I do not suggest that these are the best or only tools to use. Use whatever tools you want or need. My goal is to encourage you to start writing tools to help you do your job. Note: this is a Windows-centric article, but I suspect that Linux users have access to similar tools for automating their environment.)

Guidelines

Here are some guidelines for deciding when to write an automation tool:

  • Any frequently used term, particularly a multi-word term, is a candidate for string replacement or a macro.
  • Any procedure that requires a repeatable set of keystrokes is a candidate for a macro or windows automation script.
  • A procedure that requires a repeatable mix of keystrokes and mouse movement might be a candidate for a macro or script.
  • Procedures that are mostly mouse-based are hardest to automate.
  • Procedures that require assessing the state of an application or reading the contents of windows or dialog boxes can be difficult to script with generic scripting applications, but may be accessible using specialized scripting programs, such as FrameScript or VB for Applications.

String Replacement

String replacement programs let you automatically replace a short sequence of characters with a long sequence. For example, you could type “//sc” and the program would replace these characters with “supercallifragilisticexpialidocious.”

While use of string replacement arguably doesn’t involve much in the way of tool writing, in the context of automating common tasks, it saves a tremendous amount of time, with very little effort and almost no programming knowledge required. And lest anyone think string replacement is so obvious it doesn’t bear mentioning, when I presented a workshop on tool writing a couple of years ago, most attendees were not using string replacement tools.

I use an inexpensive program called Macro Express (www.macroexpress.com) for string replacement. There are other programs available that do this as well.

Simple Macros

Macros are typically short snippets of code that automate a series of keystrokes. While you can use macros for string replacement, macros do more than just type. They can usually execute most or all application- and system-level commands. Macros are usually executed by keyboard shortcuts or from a custom menu. Macro capability can be built into an application, as it is in Word and other Microsoft programs, or it can be managed from an external program (for example, Macro Express).

Some good tasks for macros include:

  • Frequently used index formats
  • Text formatting
  • One-time tasks that are worth automating if you can write and debug the macro in less time than you can do the job by hand

Macro programs usually let you create macros in one of two ways:

  • Record as you do the task
    • Advantage: No programming needed
    • Disadvantage: Timing issues; errors require repeating the process
  • Type a series of commands in a macro editor

Complex Macros and Windows Automation Scripting

Complex macro scripting and Windows automation scripting are more advanced levels of automation that may involve programming constructs such as variables, loops, conditional blocks, and so on. You might also build your own graphical user interfaces (GUIs) to manage your scripts. Since “macro” applications can create macros at this level of difficulty, the reason I distinguish complex macros from simple macros is that the degree of difficulty of the scripting process is greater and the goals are more ambitious. I have also found that using a Windows automation tool designed with a robust scripting language gives me more programmatic control than my macro program and it is easier to maintain the scripts than the code that gets created by a macro tool designed more for a non-programming audience.

For example, here is what I see in the direct editor of Macro Express after I’ve written a macro that does some index entry formatting (the writing process is less opaque):

Here is that same sequence in the Windows automation tool AutoIt (www.autoitscript.com):

Which would you rather edit?

Here are some ideas for complex scripting:

  • Button bars for common tasks
  • Control panels for running applications or special scripts
  • Automated UI tasks
  • GUIs created on top of console-based apps
  • Automated testing utilities
  • Application configuration

Figure 1 illustrates a small tool for automating my final PDF production process. It also automatically pages through a PDF file—something that you can’t do natively in Adobe Acrobat.

Figure 1. PDF Production Palette

Application-Level Scripting

Application-level scripting is a process that taps directly into an application using the programmatic hooks that it provides to outside applications. For FrameMaker, this means the FrameMaker SDK (if you speak C++), FrameScript (www.framescript.com), or for FrameMaker 10, the new ExtendScript feature. For Word and many other applications, this means using Visual Basic for Applications.

Application-level scripting allows you to exert a level of control that is more certain than an external windows manipulation script can provide. However, this is certainly the most difficult of the tool-building approaches. It requires the strongest programming skills.

An Extended Example

I will now present a series of successively more complex examples to demonstrate the four types of tool writing. The examples automate a procedure that almost every writer has to do at some time or another–write index entries. Since I use FrameMaker, the example will use FrameMaker syntax.

Suppose that you want to index all of the references in a manual to dialog boxes and you want the following entries for each dialog box:

New Widget dialog box

Dialog box New Widget

(Note that my format includes bolding the name of the dialog box.) To create this index entry in FrameMaker, I would put the following text in the Marker dialog box:

New Widget dialog box;dialog box:New Widget

String Replacement Example

If I have 50 dialog boxes to index, I will have to type at least 50 index markers that are exactly the same except for the name of the dialog box. I can make my life much easier by using a string replacement application for the text that gets used over and over. For this particular marker syntax, I need two string replacements: one for and one for all the text between the two instances of the dialog box name. So, let’s say that in my string replacement program I map “” to the shortcut “/b” and map “_dialog box;dialog box:” to “/dbx” (the underscore is to show a space). To create a dialog box index marker, I complete the following steps:

  1. Put the cursor in the Marker dialog box.
  2. Type /b. The computer replaces the shortcut text with .
  3. Type the name of the dialog box.
  4. Type /dbx. The computer replaces the shortcut text with _dialog box;dialog box:.
  5. Type the name of the dialog box.
  6. Press Enter to insert the marker.

This process cuts down the amount of typing for each index marker dramatically. If I did nothing else in the way of tool writing other than creating these string replacement shortcuts and similar shortcuts for other common indexing text, my life would be much easier.

Macro Example

However, this isn’t enough automation for my tastes. After all, I am still typing the name of the dialog box twice. I would really like to eliminate that extra typing. To automate beyond simple keystroke replacement, we need to use a macro.

To write the macro, let’s change our procedure slightly and then automate it. For the macro, we want to automate the following procedure:

  1. In the Marker dialog box, type the name of the dialog box.
  2. Select the dialog box text and copy it.
  3. Move the cursor to the front of the marker text.
  4. Type .
  5. Move the cursor to the end of the marker text.
  6. Type dialog box;dialog box:.
  7. Paste the name of the dialog box.

Translating this procedure into keystrokes for the macro application, the sequence (starting from when we are done typing the name of the dialog box) would be:

Shift+Home (select the dialog box name)

Ctrl+c (copy it)

Home (move the cursor to the start of the marker)

(We could use our string replacement shortcut here and it would work, but it is better not to rely on another program. The computer will type this so we never have to type it ourselves again.)

End (move the cursor to the end of the marker text) _dialog box;dialog box: (just type this in the macro editor)

Ctrl+v (paste the dialog box name)

(You could add an Enter here if you want to insert the marker automatically, or leave it out if you want to review it first.)

Now we can type the name of the dialog box in the Marker dialog box, then type the shortcut (/dbx) assigned to this macro, and the rest of the marker will be completed. We have eliminated almost all typing for this repetitive index marker. Do this for the other repetitive markers and you will save even more time than you did with just string replacement. For many years, this was about as far as I ever went with tool writing and was perfectly happy with the results.

(By the way, you don’t think I’m typing “dialog box” over and over in this article, do you? I am using my string replacement shortcut.)

Windows Automation Scripting Example

There is one problem with creating a library of string replacement shortcuts and macros—if you don’t use them often enough, you forget the shortcuts. For an intermittent activity like indexing, this was a constant problem. My solution for this problem was to create little button bars for frequently and infrequently used macros. The tool I use for this is AutoIt, which is a tool designed for Windows automation tasks. It allows you to write scripts and create simple to moderately complex GUIs. You can compile the scripts to an executable file so that people who don’t have AutoIt installed can run the programs.

Figure 2 shows the index editing toolbar I created using AutoIt.

Figure 2. Index Automation Palette

Here is the rough outline of how to create a button bar that would run the indexing macro that we wrote in the previous section:

This will work fine; however, it is better to script the button action in the native scripting language rather than calling another program to do the work. The $dialogBox function uses the syntax shown earlier in this article when I compared macro syntax to AutoIt syntax.

As you can see from Figure 2, my indexing palette has buttons for a lot of my common index marker types. It also will also copy selected text to an index entry.

Application-Level Scripting Example

Now let’s turn our attention to the complex scripting level of tool writing. At the start of this article, I stated that in addition to doing things faster and automating repetitive actions, you might want to write tools to do things that your application doesn’t do, or do them in a way more congenial to your workflow. After some time using an indexing palette based on AutoIt scripting, I migrated my indexing to a GUI written using FrameScript. Since FrameScript hooks directly into FrameMaker instead of operating outside it, like a macro or AutoIt script does, I get more control and quicker execution. My indexing GUI completely replaces the FrameMaker Marker dialog box for adding index markers.

In addition to automating some standard index marker formats, my indexing palette lets me automate index inversions. Since I work in structured FrameMaker, I have also added the ability to apply attributes to my index markers. Figure 3 shows my custom indexing palette built with FrameScript.

Figure 3. Index Entry Dialog Box Built with FrameScript

In Figure 3, you can see that I have buttons for some of the same functions as in Figure 2, for example, Dbx, Func, Class, and Param (abbreviated). But now, I also have a field for entering the index entry text. Instead of acting on the native FrameMaker index marker dialog box from an external application, I completely replace it. If I want an inverted entry, I type the main index term in the Index Entry field and the subordinate term in the Invert Index Entry field. If I want to pluralize the secondary term, but not the primary, I can do that. For example, if I want the entries to be:

entity: creating

creating entities

I type “entity” in the Index Entry field and “creating” in the Invert Index Entry field. Sometimes I type the entries backward, so I can reverse the pluralization if I want to. FrameScript code is a bit less obvious than AutoIt, but here are a few snippets that show how to create some widgets and insert a simple index entry:

This series of examples shows how to automate a common, repetitive function—inserting an index entry. It starts with a simple approach—string replacement—then moves through successively more complex and capable methods until the last example replaces the native index creation dialog box. I have several little button bars and focused dialog boxes like these that help me do common tasks more quickly. They also help me do infrequent tasks without spending time refreshing my memory about how they work.

Conclusion

My goal in this article has been to stimulate your interest in writing tools to make your life as a writer easier and to provide a change of pace and a little fun along the way. I am sure you will think of quite a few ways to apply these tool development methods to your daily workflow and will come up with ideas for tools that you could write. I hope that you will soon be adding new, homegrown tools to your tech writing toolbox.

Fred Wersan (fwersan@mak.com) is principal technical writer at VT MAK in Cambridge, MA, which develops software to link, simulate, and visualize virtual worlds. As the sole technical communicator, he is responsible for writing and delivering manuals, online help, tutorials, and other product documentation. For many years, he has been writing his own tools to manage his writing and production processes.

Tags