Macros Help

Name:	Macros
Version:	2.3
Last update:	2019-11-27 14:12:52

Introduction
What Is a Macro?
Defining a Macro
The Saved Macros package
- Saving Macros
- Macro Utilities
Keyboard shortcuts
Writing Good Macros
Differences Between Alpha and Emacs
Known problems
License and Disclaimer

Introduction

This help file describes the Macros facilities in Alpha: some basic commands are available by default to record and execute temporary macros and additionally, there is a package named Saved Macros which lets you save macros between sessions.

What Is a Macro?

A macro is a sequence of recorded actions that can be played back again. This is useful to automate some repetitive tasks. The following kinds of actions can be recorded:

selection of a menu item;
key bindings entered from the keyboard;
clicks on simple toolbar items in document windows.

Key strokes which do not correspond to a key binding are not recorded. Mouse movement or entries in system dialogs are not recorded either. Even with these limitations, you will discover that macros can save you time through easy automation of repetitive tasks.
When do you make a macro? Whenever you find yourself selecting the same menu items and typing the same keyboard shortcuts over and over again, then a light should go off in your brain telling you its time to make a macro. Once you make a macro, you can name it (that is, save it) for future use. Over time you will build up a library of Saved Macros that you can invoke any time you need them.
Things you can do with macros:

basic textual markup;
reformat tables and files;
complex copying and pasting between edit windows.

Alpha's implementation of macros is similar to that of Emacs, but there are subtle differences. Remember, Alpha is not Emacs! You don't need to be an Emacs guru to use keyboard macros in Alpha. Since macros are a simple way of creating valid Alpha text manipulation commands, every user will benefit from a basic working knowledge of how to use macros.
See this Macros Example hyperlink for a little macros tutorial.

Defining a Macro

Defining keyboard macros can be done with the commands found in the Tools ↣ Macro Recording menu. This menu is always available. This submenu has, by default, the following items:

Menu Item	Default Shortcut	Action
Begin Recording	`F13`	Start recording keystrokes.
End Recording	`F14`	End recording.
Execute Last Macro	`F15`	Invoke Last Recorded Macro.

Begin recording a macro by selecting the Begin Keyboard Macro menu item, pressing its keyboard shortcut equivalent, or by pressing Control-X ( -- the message Defining Keyboard Macro ... will appear in the status bar to inform you that your subsequent keystrokes will be recorded. Once you have started a keyboard macro, Alpha will record every menu selection you perform and every keyboard shortcut you execute. Remember, nothing you do with the mouse is recorded, so you should move the insertion point with cursor movement shortcuts. (See Emacs Help for a list of Emacs cursor movement shortcuts.)
To end the macro, use the End Keyboard Macro menu item, its keyboard shortcut, or press Control-x ) -- this tells Alpha to stop recording your actions. A recording session does not terminate automatically, so don't forget to end it.
During macro recording, Alpha behaves normally responding to commands and keystrokes.
To invoke your macro after you have recorded it, press Control-X E (or use the menu or keyboard shortcut ...). Alpha will play back your recorded actions. The key combo Control-X E invokes only the last recorded macro. Any macro you want to save should be named.
These recorded macros remain available during an entire session but disappear when you quit Alpha.
The Macros Example hyperlink is still available for a tutorial !

The Saved Macros package

Saving Macros

The Saved Macros package allows you to make your macros persistent between sessions. It lets you name the last created macro and stores its definition on disk so that you can find it again next time you launch Alpha. One can save as many macros as desired.
Once this package has been turned on by selecting Alpha ↣ Global Setup ↣ Features, several new menu items are available:

items are added in the Tools ↣ Macro Recording to let you save, rename, copy or delete macros.
a new submenu Tools ↣ Saved Macros is inserted in the Tools menu to gice access to the saved macros.

Click here to display the Features Preferences dialog and activate the Saved Macros package.

Macro Utilities

When the Saved Macros package is active, the Tools ↣ Macro Recording menu includes several macro utilities which allow you to save the Last Recorded Macro that you created, and manipulate the collection of Saved Macro Scripts that are stored in your Alpha's Appication Support folder.
The menu items include:

Display Last Macro: Opens a new window displaying all of the commands in the Last Recorded Macro. If you need to modify this script, you should first name this macro using the Tools ↣ Macro Recording ↣ Save Last Macro… command.
Save Last Macro…: Save the Last Recorded Macro. Prompts you to enter a name for your new macro, and inserts this new name into the Saved Macros menu. All Saved Macros will be remembered upon subsequent restarts of Alpha. Names should only contain alpha-numeric characters and spaces. All saved macros are retained as files in your Application Support/Alpha/Macros folder. Select the menu command Tools ↣ Saved Macros ↣ Show Macros Folder to see this folder in the Finder.

Once you have saved a macro, it is listed in the Tools ↣ Saved Macros menu. Your collection of Saved Macros can be manipulated in the following ways, using the following Tools ↣ Macro Recording utility commands.
These items are dimmed if there are no currently saved macros.

Edit Saved Macro…: Opens a dialog allowing you to select any Saved Macro to be edited. Once you have made your selection, the Saved Macro's script will be displayed in a new window. You can edit the Saved Macro as much as you like, testing it as you go to see if the new version behaves in the ways that you want.
The contents of the script contain AlphaTcl commands. Knowing a little something about the Tcl programming language might be useful for editing the Macro Script, but in most cases you can figure out the minor changes that you need to make. Feel free to experiment as much as you like!
Rename Saved Macro…: Offers a dialog allowing you to select any Saved Macro to be renamed. Once you have made your selection, you are prompted for a new Macro Name. Any keyboard shortcut associated with the old Macro Name will be transferred to the new one.
Copy Saved Macro…: Opens a dialog allowing you to select any Saved Macro to be copied. Once you have made your selection, you are prompted for a new Macro Name. After the Saved Macro has been copied, you can edit it to change its script.
Delete Saved Macro…: Offers a dialog allowing you to delete any previously Saved Macros. These will be permanently removed from the Tools ↣ Saved Macros menu.

Once you have saved a macro, it is listed in the Tools ↣ Saved Macros menu. Selecting a Saved Macro Name from this menu will execute it in the active window. The appearance of these Saved Macros in the Saved Macros menu can be changed by selecting the following commands.

Hide Saved Macros…: (This item is dimmed if all Saved Macros are hidden.)
Removes any Saved Macros from the Saved Macros menu, but does not delete them permanently. Any Hidden Macros can be shown again with ...
Show Hidden Macros…: (This item is dimmed if there are no currently Hidden Macros.)
Re-inserts any previously Hidden Macros into the Saved Macros menu.
Menu Shortcuts…: (This item is dimmed if there are no Saved Macros.)
Opens a dialog allowing you to assign/change the keyboard shortcut associated with any Saved Macro. Saved Macros that are hidden and subsequently re-shown will retain any assigned keyboard shortcut.
Note that keyboard shortcuts set by other menus or modes may take precedence over the shortcut that you have selected. Before choosing a shortcut, you should use the Alpha ↣ Global Setup ↣ Keyboard Shortcuts ↣ Describe Shortcut menu item to ensure that the shortcut that you want is available. See the file Keyboard Shortcuts for more information.
Remove Shortcuts: (This item is dimmed if there are no Saved Macros with keyboard shortcuts.)
Offers a dialog allowing you to remove any previously assigned keyboard shortcuts that you assigned to your Saved Macros.

Keyboard shortcuts

If you don't have an extended keyboard (or even if you do), you can change the default F13, F14 and F15 keyboard shortcuts for Macro Recording commands by selecting Tools ↣ Macro Recording ↣ Menu Shortcuts… as explained above. This menu item is available when the Saved Macros package is active.
Alternatively, if you activate the emacs package, another set of keyboard shortcuts is defined as shown in the following table:

Menu Item	Emacs Shortcut
Begin Recording	`⌃X (`
End Recording	`⌃X )`
Execute Last Macro	`⌃X E`

Writing Good Macros

With practice you will become proficient at constructing macros which work in all situations. The most important principle in creating good macros is the use of absolute, rather than relative commands. In the double-space example used in the Macros Example, we pressed Control-E (⌃E) to move to the end of the line rather than spacing to the end of the line with a series of Control-F (⌃F) keypresses. A good macro will successfully work on the target text and prepare itself to be repeated. In this example, the last command in the macro moved the cursor to the next line, precisely where it needs to be for the repeat performance.
While macros are an easy way to automate repetitive typing tasks, they are not an alternative for writing your own procedures. There are many things that you can't do with a macro. Loops, if-then conditionals, and searches cannot be recorded with a macro (although they can be easily added manually.) Some macros might be good starting points, however, for scripting your own procedures.

Differences Between Alpha and Emacs

In the double-space example used in the Macros Example tutorial, we used Control-E Control-F to position the cursor on the next line. Control-N is just as good in Alpha; unlike Emacs, Alpha does not add a new line to the buffer if Control-N is issued on the last line of the file. If you use Control-N in Alpha and call the macro more times than there are lines in the file no extra lines are added.

Known problems

Please report any problem or bug you encounter to Alpha's Bug Tracker.
A known issue with saved macros is the fact that some key bindings are associated with menu procs which expect a menu token as argument: menu tokens are dynamically attributed when the menu is first created but there is no guarantee that next time you launch Alpha a given menu will have the same token. This depends on the order in which packages are activated. This is a weakness of the macros system. If this kind of problem occurs with a saved macro, you will have to record it again.
Emacs users will be used to setting up a macro with a search by pressing Control-S. Alpha is not Emacs! Text typed into the status bar is not recorded. The command Control-S (quickFind) is recorded, but none of the search text is. In order to couple your macro with a search you will have to learn a little Tcl (as shown above).
Recursive edits do not work in Alpha. All keystrokes you type during macro recording are collected. (A recursive edit in Emacs is invoked with Control-X Q or Control-U Control-X Q and provides a way to pause the macro for user enterable text. While in the recursive edit, the keystrokes are not recorded. During the macro playback, the macro will pause for the user to enter text when the recursive edit is encountered.)

License and Disclaimer

The original author of this documentation is Donavan Hall hall@magnet.fsu.edu.
Copyright (c) 2000-2019, the Alpha Community.
All rights reserved.
The Macros package is free software and distributed under the terms of the new BSD license:
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the Alpha Community nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE ALPHA COMMUNITY BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.