Creating and Saving Macros in JOVE: Introduction and Part I
Introduction
There are a few things you will need to know in order to create, save and recall JOVE macros. JOVE macros are relatively simple to write, but they can be amazingly complex in their behavior. This helpsheet has three parts. The first part (which follows this introduction) explains how to set up JOVE to record and save your macros for later use. The second section deals with advanced macros that will allow you to run shell scripts from within JOVE, and the third section deals with making macros that interact as a suite. The first section is written in such a way that first time users of JOVE will be able to record and save their macros within fifteen minutes.
Major Parts of this helpsheet
- Creating and Saving Macros
- Interacting with the Shell: Parsing and Mulitidocsing within JOVE
- Creating macro suites: context-sensitive editing
I know some of you loathe instruction manuals. You know this loathing to be a great failing, one that keeps you from learning the subtleties and features of a program. Nonetheless, you hate reading helpsheets and manuals. If you are one of these people here's the quick-and-dirty way to learn how to record and save macros, or at least as quick-and-dirty as it's likely to get. You'll have to read and follow the instructions under "Preparing JOVE to save your macros" from start to finish. Sorry. But from there you can skip directly to the Summary of Part I.
WARNING
The Summary of Part I assumes that you are quite familiar with the syntax of the JOVE macros file, and unless you already have this familiarity or are willing to spend time scrutinizing JOVE macros code, you'll have to spend the fifteen minutes going through "Creating and Saving a Macro"
But before you begin, I will refer you to two documents that will help you make your JOVE macro toolbox more versatile and useful. The first document is a reasonable attempt at a manual for JOVE, even if it is a little short on examples and how-tos. That document, U-003, explains how to invoke JOVE, issue commands, and customize options, but its primary usefulnes lies in the fact that it contains a canonical listing of all the commands that can be issued from JOVE. U-003's listing is organized by group and also identifies the key-bindings (keystroke combinations) that can be used to issue those commands. You can get to document U-003 by clicking here. If you will be using JOVE regularly, I recommend that you visit and print out that document. The second document is an in-depth manual for JOVE. It describes many different asepcts of JOVE, everything from how navigating documents efficiently to searching with grep. If you are an intermediate or advanced user of JOVE, you should visit and print this document out, as it provides detailed explanations of all aspects of JOVE, including an alphabetical listing of all commands that can be issued in JOVE. That document, U-003a, can be accessed by clicking here.
Part I: Preparing JOVE to save your macros.
You will have to create two plain-text files in order to create and save your macros, and you can create these files using JOVE. The instructions for building these files is covered below in
What the .joverc and macros files do
The first file is named ".joverc". Whenever you invoke JOVE, JOVE searches your home directory for ".joverc". The file ".joverc", if and when it exists, tells JOVE what services to initialize and what options to turn on and/or off. ".joverc" also tells JOVE the name of the other plain-text file we are interested in.
This second file is the one that will contain your saved macros. This second plain-text file can be named anything (except ".joverc") and can exist in any directory from which JOVE is invoked. It is probably simplest if you name this second plain-text file "macros". This helpsheet assumes you will name this file "macros", and the instructions below depend upon this file being named "macros".
But what does it mean that this second plain text file "can exist in any directory from which JOVE is invoked"? Well, it means that if you have two directories, say one named "teiEditing" and another named "htmlEditing", each of those directories could contain a unique set of macros. Each set could be tailored to do special routines. JOVE can do this because it gets its macros from the macros file that is inside the directory from which you invoke JOVE. If there is no macros file, then JOVE does not load any macros.
Let's get started creating these two files.
Creating .joverc
First, in your home directory (you can get there by issuing "cd ~" at the command line, just to be sure), invoke JOVE with the command
jove .joverc
This will invoke JOVE and you will be editing a file named ".joverc"
Type the following into this file:
bind-to-key execute-macro ^o
bind-to-key name-kbd-macro ^n
bind-to-key shell-command ^q
source macros
Creating the .joverc file
Save this file and make sure that it is named ".joverc". JOVE has several unused keyboard sequences. [CTRL-o] (the "control" key and the letter "o") [CTRL-n] and [CTRL-q] are three such unbound keyboard sequences. The first "bind-to-key" command tells JOVE that the command "execute-macro" can be issued using ^o ( the [CTRL-o] sequence). The same is true for the other two "bind-to-key" lines.
The last line tells JOVE that the name of the plain-text file that contains its macros (its "source") is "macros". If this last line had read
source foobar
JOVE would take its macros from a file named "foobar". However, "macros" is probably the best name because it will help you identify which of your local files contains JOVE macros. If JOVE does not find the named file in the directory from which you invoke JOVE, no macros will be loaded
Creating the macros file
Now, you need to create a second file in the directory from which you will invoke JOVE. At the command line, you can issue the command
jove macros
to begin editing a file named "macros". In this file type the following:
define-macro smacros ^[xwrite-macros-to-file macros^M
define-macro print ^Qlpr -P etext_l1 ^[i^X1
define-macro quit ^X^C
Creating the macros file
Save this file and make sure it is named "macros". The details of the above commands are explained in the second section of this helpsheet.
In order to use the macros you have just created, you will need to quit JOVE and invoke it again. When you reinvoke JOVE you will be able to create and save your macros. The following will guide you through the steps of creating and saving a macro.
Creating and Saving a Macro
Invoke JOVE from the diretory in which your "macros" file is located. This can be your home directory (which contains the ".joverc" file), but it need not be.
Here is a simple macro that will save you a bit of typing. This example macro will place the cursor at the beginning of the line, type a blank line, type the string
<pb n=""/>
type another blank line, and will place the cursor between the pair of double quotation marks so you can type in the page number. The result will be a page break tag on a line by itself and surrounded by two blank lines.
Writing the <pb/> macro
First, you will have to tell JOVE to start recording a macro. To do this type (square brackets indicate a key-combination)
[CTRL-x] (
That is, hold down the CTRL key while typing the letter "x". Next, type ( by holding down the [SHIFT] key and pressing on the "9" or "(" key.
Next, type the following (everything within square brackets are keystrokes; ignore the line breaks at the end of each line)
[CTRL-a]
[RETURN]
<pb n=""/>
[RETURN]
[RETURN]
[ESC-r]
">
[RETURN]
Now, you need to tell JOVE to stop recording the macro. Do this by typing
[CTRL-x] )
JOVE has now recorded your macro. If you've ever recorded a macro, you know that to execute this macro, you need only type
[CTRL-x] e
But what if you want to have access to this macro the next time you ran JOVE? Well, first you must name the macro. The normal key sequence to do this would be [ESC-x] name-kbd-macro [RETURN], but now you need only type
[CTRL-n]
and JOVE will prompt you to name the keyboard macro. For this example, you would type in
[CTRL-n]
pb
[RETURN]
This series of keystrokes tells JOVE to run the macro that is bound to [CTRL-n] (which is "name-kbd-macro" if you've followed the instructions up to this point). JOVE then waits for you to name the macro, and by typing pb and hitting [RETURN] you tell jove to name the macro "pb".
WARNING
You may name a macro using any combination of characters except spaces). Unfortunately, a bug in JOVE's name-kbd-macro command will accept spaces, but when you try to execute a macro so-named, you will not be able to run it. Macro names are case-sensitive.
Now you can invoke the macro you just recorded and saved by simply typing
[CTRL-o]
pb
[RETURN]
You alo can combine this with [ESC] [INTEGER] where "INTEGER" is any positive integer. For example [ESC] 5 [CTRL-o] pb [RETURN] will execute our "pb" macro 5 times.
But this macro will live only as long as you are running this session of JOVE, unless you save it to the macros file. The way you do this is by typing
[CTRL-o]
smacros
[RETURN]
This last command will save any macros you have recorded by executing the macro named "smacros" (again, this depends on your having followed the instructions outlined above in "Creating the macros file"). Once you've saved your macros with the last command sequence, you will be able to quit JOVE and access the macros you've recorded, named, and saved once you reinvoke JOVE.
This ends the basic tutorial for setting up JOVE to record and save macros. There are a few things you should note.
1. JOVE looks for a macros file in the directory from which it was invoked. This file's name has to match the name in the "source" line of the ".joverc" file.
2. To save a keyboard macro for later execution, it must first be named.
3. Once you have named the keyboard macro, you must save the macros file.
WARNING
4. If you record a macro and give it the name of a macro that already exists, the new macro will overwrite the old one.
5. A few of the commands we've used involve macros you wrote when first writing the macros file. One of these macros is named "smacros" ("s" is for save) and this macro has as its argument "macros". If you decide to name your macros files something else (e.g. "jovemacros") make sure that the first line of macros files is changed. In this case,
define-macro smacros ^[xwrite-macros-to-file macros^M
would become
define-macro smacros ^[xwrite-macros-to-file jovemacros^M
It is a good idea to name your macros something easy-to-remember and descriptive. However, for often-used macros, naming your macro a single character can be very handy. For example, one of the macros that we've written up is the macro named "q". In the macros file, it's line looked like this:
define-macro quit ^X^C
This macro quits jove for you.
It's arguable that typing [CTRL-x] [CTRL-c] is actually less time-consuming than typing [CTRL-o] q [RETURN]: two keystrokes/combinations are fewer than three. However, as you write and use your saved macros more often, you will find that the [CTRL-o] portion of the macros "disappears" from the sequence because it is natural to type, just as typing [RETURN] is "natural". As a result, executing commands by using the "gateway" [CTRL-o] immediately becomes much faster for all commands, especially if those commmands have single-character names.
Single-character macro names can greatly improve your agility and make your tagging of texts more efficient.
Here is a breakdown of the steps to record, name, and save macros.
Summary of How to Record and Save a Macro
To record a macro:
[CTRL-x] (
<<sequence of actions to be recorded>>
[CTRL-x] )
To name a keyboard macro:
[CTRL-n]
<<name of macro>>
[RETURN]
To execute a named macro:
[CTRL-o]
<<name of macro>>
[RETURN]
And a specific, but important, instance of this, is saving the macros you've recorded and named before leaving JOVE, and you do this with
[CTRL-o]
smacros
[RETURN]
At this point, you are ready to build your own suite of macro commands. The easiest way to do this is to record your macros, name them, and save them.
If you're ambitious, you can peek into the macros files after recording a macro and see exactly how JOVE interprets keystrokes. Such intimate "hacker's" knowledge will help you make more sophisticated and useful macros, and understanding the syntax of JOVE's macros is easier than it might at first seem. The following section covers various aspects of JOVE's macro syntax, and you can always turn to it after you've experimented a bit on your own.