Tutorial: Adding a keyboard shortcut to change a paragraph into a warning

[Su-Laine Yeo]

It is often possible to add shortcuts to XMetaL to perform frequent tasks quickly. A script that you can invoke through a keyboard sequence, menu command, or other action is called a macro. For complex tasks, you might have to actually write the macro code in VBScript or JScript. For some simple tasks, you can use the “Record Macro” feature and have XMetaL write the code for you.

In this tutorial, you will learn how to set up a macro using the “Record Macro” feature and hook it up to a keyboard sequence. No knowledge of scripting or programming is necessary. The example in this tutorial refers to particular elements used in DITA topics, but you can apply the concepts to other types of elements or attributes that you want to quickly insert.

Background:
In DITA, a paragraph uses the

element, like this:

Lorem ipsum dolor sit amet.

A warning uses a attribute and two attributes.

Lorem ipsum dolor sit amet.

Because changing the element type and then assigning these two attributes is time-consuming and error-prone, writers often want a keyboard shortcut to do it.

Procedure for setting up the macro:
1) Open a DITA topic containing at least one paragraph.
2) Click View > Element List to display the Insert Element pane.
3) Click View > Attribute Inspector to display the Attribute Inspector.
4) In the document, click anywhere within a paragraph.
5) Click Tools > Record New Macro.
6) In the bottom of the Insert Element pane, select the Change radio button.
7) In the Insert Element pane, double-click note.

In your document, the

element changes to a element. Notice that the word “Note: ” automatically appears at the front of the element, because the DITA stylesheet (.CSS) files are configured to style elements this way.

8) Make the Attribute Inspector pane look like this. Note that there are two attributes you must change:

[img]http://img141.imageshack.us/img141/2456/35498457.png[/img]

Notice that in your document the word “Note: ” at the front of the element automatically changes to “Warning: “.

9) Click Tools > Stop Recording. The Define New Macro dialog appears.

10) In the Define New Macro dialog, from the Create this macro for dropdown choose Application (username). By choosing this option, you've made the macro available for all document types.

11) In the Macro name field, type Change to warning.

12) Select the Alt and Shift checkboxes. In the Key field type W. This assigns the macro to the keyboard sequence Alt+Shift+W.

[img]http://img169.imageshack.us/img169/8687/20900680.png[/img]

Result:
To quickly test the macro, click in a

element and then press Alt+Shift+W. You should see the word  “Warning: ” appear in front of the paragraph you just clicked in. In Tags On view, you should also see the

tags change to tags.

Internally, XMetaL appends some VBScript to your XMetaL.mcr file. XMetaL.mcr file  is here: C:Documents and SettingsApplication DataSoftQuadXMetaL5.x. You can open the XMetaL.mcr file in any text editor, such as Notepad, to see what has changed.

Note that there is also a file named XMetaL.mcr in a subfolder of your Program Files folder, and the “Record Macro” feature does not touch it.

By default, scripts are recorded in VBScript; if you wish to edit them later and prefer JScript, you can change the default by setting the following INI variable:

default_macro_language = JScript

Limitations:
Scripts produced by the “Record Macro” feature tend to be limited in terms of detecting edge cases and providing error feedback. The macro created using the above procedure works well if the insertion point is in a

or element to start with. If the insertion point is in an element that can't be changed into a without making the document invalid, the macro stops. If the insertion point is in an element such as within a paragraph, you will end up changing the into a warning within the paragraph.

If you know how to write VBScript, JScript, or another scripting language supported by XMetaL, you can create a macro script to do more graceful error-checking and error feedback. However, for non-programmers who just want to set up something quickly to provide a shortcut for a simple task, the “Record Macro” feature can be very useful.

Reply

[Author]

Posts