Category : Word Processors
Archive   : VDE173.ZIP
Filename : VMACRO.REF

VMACRO.REF
----------
Macro Reference for the VDE Editor:
version 1.73 (17 Aug 1994)

(c)1987-94, E. Meyer



================================ CONTENTS ==================================

(For QUICK START, SYNTAX, GENERAL INFORMATION etc. see the file VDE.DOC)

(For a comprehensive COMMAND REFERENCE, see the file VDE.REF)

8. MACRO INSTRUCTIONS:
A. Keystrokes and notation
B. Defining macros
C. Recording macros
D. Assigning macros to keys
E. Macro programming
F. Examples of useful macros

9. MACRO REFERENCE, alphabetically by topic:
Autoexec macro, Chaining and calling, Counter variable, Define or
record macro, Error handling, Function keys, Function key labels, Key
definition files, Labels and jumps, Pause, Tests and loops, Toggle
control.

(For use of the VINST installation utility, see the file VINST.REF)


================================ 8. MACROS =================================

A. KEYSTROKES AND NOTATION

Essentially, a macro is a sequence of keystrokes representing text and/or
VDE commands, which can then be repeated automatically or stored to a key for
future use in order to make frequently performed tasks easier.

While this may sound quite straightforward, it is obviously necessary to
get such a key sequence EXACTLY correct for the macro to perform as intended;
therefore, the representations of macros in this manual present many
possibilities for confusion. First, some basics: the characters "[]" are
often used to signify the pressing of a single key, like "[Esc]" -- but they
are not used when that key is exhibited as part of a macro or multi-key
command, like "Esc&F2". Also, don't be confused by the fact that a single
bracket can also appear as part of certain macro commands, like "Esc~^M]".
The character "^" is normally used to indicate control-key combinations, as in
"^M" for Ctrl-M; but there are special cases when the character "^" itself
needs to be typed, as in "Esc&^F2".

A space will often be used here to separate groups of keystrokes to make
a macro easier to read and understand -- but these spaces ARE NOT part of the
macro, and should not be typed in if you are trying to define it. Any spaces
that actually ARE part of the macro and SHOULD be typed in will be represented
by the underline character "_".

Finally, there are occasional differences between the keystrokes you
would actually type in order to perform a task, and those that must be typed
in order to enter this sequence at the macro definition prompt. At all VDE
string prompts, there are certain control-characters which control the
entering of the string itself; for the macro definition command Esc[, this is
a somewhat shorter list than for other prompts, but it still includes:
[Enter] or ^M or ^J -- terminates entry of the string
[BkSp] or ^H -- deletes the last character entered
^R -- replays the last macro entered
^P -- enters codes like these in macros
(Also, of course, ^[Break] aborts string entry.) This means that actually
ENTERING Enter/^M/^J or BkSp/^H or ^P (or ^R as the first key) AS PART OF THE
MACRO ITSELF requires the ^P prefix first. If you forget this prefix, of
course, you will instead see the key perform its function indicated above.
Throughout this manual, macros are presented as they actually function,
since this is easier to understand; that is, they DO NOT include such extra ^P
prefixes. If you are trying to enter a macro at the definition prompt, you
must remember to use caution with the above control keys! (See also ^P
NESTING, below.)
Another useful fact to remember is that two-key commands accept either an
ordinary letter or a control key for the second key -- that is, ^K^M and ^KM
can be used interchangeably to enter a placemark. But entering ^K^M in a
macro definition would present a problem (requiring you to type ^K^P^M
instead), whereas ^KM is just fine. And, last, the Left-arrow key or ^S is
easier to enter into a macro than [BkSp] or ^H, since no prefix is required.

EXAMPLE: Consider the following macro, whose purpose is explained more
fully below under EXAMPLES OF USEFUL MACROS:

^QS ^X Esc=_] Esc=^M] ^S_^D Esc![

If you want to type this in at the macro definition prompt, you should note
that there are only two actual spaces IN the macro, indicated by "_"; the rest
are present merely for visual separation of different groups of keystrokes.
Also, the ^M will require a ^P prefix. So after invoking the Esc[ command to
define a macro, the actual keys you would type are:

Macro: Ctrl-Q S Ctrl-X Esc = Space ] Esc = Ctrl-P Ctrl-M ]
Ctrl-S Space Ctrl-D Esc ! ]

That's a total of 18 keystrokes, not including a final [Enter] to terminate
the definition. If you have done this correctly, you will see on screen
something like this (the underlined letters will be highlighted as control-
codes):
Macro: QSX[= ][=M]S D[![
- -- - - - --
Note that the [Esc] key, which is actually ^[, displays as a highlighted "[".


----------------------------- B. DEFINING MACROS -----------------------------


To DEFINE a macro, type Esc[. Macros execute EXACTLY as though you had
typed the given keys yourself; this means that every keystroke, including
answers to prompts, [Enter]s, and so on, must be properly included, so plan
ahead carefully, with pen and paper if necessary.
Any PC keys can be entered at this prompt; a few, like arrow keys, will
display with a recognizable symbol, but most (PgUp, etc) will simply display
as a highlighted asterisk "*". (VINST is capable of displaying the full
keyname, if you later edit the definition.) Even MenuBar commands (except
{User:}) can be used in macros, with the ^[Esc] command (see MENUBARS).

Once you have entered the macro definition, you will be asked whether you
want to Use it immediately, or Store it (on storing, see ASSIGNING MACROS TO
KEYS). If you're going to use it now, you need to decide whether you want the
macro to repeat (and if so how many times), and whether you want to watch it
happen or not:
VDE asks "Make Quiet, No-repeat, Both?" Reply "Q" for
Quiet (fast) operation, or press [Enter] for visible
(slower) execution. (The "N" option is intended for
storing keys, but can also be typed here to skip the next
question.)
VDE asks "Repeat count?" Type the number of times to
execute (0-254), or just [Enter] for 1; or "*" to repeat
indefinitely.

When a macro executes, the "!" flag appears in the header; normally, you
can also see its effects as it executes. You can cancel it at any time by
pressing [Esc]. If you choose to speed up macro execution by specifying
"Q"uiet mode, only the header will be updated as the macro runs. (Don't do
this if the macro uses any commands that require user input -- the necessary
prompt would not display!)
By default, macros will stop automatically if an error condition occurs,
in which case the error message will display briefly; or if the cursor
attempts to move past the top or end of the file, in which case no error
displays. (See also ERROR HANDLING.) Thus some macros will halt on their own
when they reach the end of a file; others may have to be terminated manually,
by pressing [Esc].
Once defined, a macro can be recovered by typing ^R to replay it at the
Esc[ prompt, so that you can choose to Use it again, or Store it if you did
not previously do so.
^F, when entered as part of an input string, normally inserts the name of
the current file (see PROMPTS). In a macro definition, it remains an ^F,
expanded to the current filename only when the macro actually executes. This
can be useful to refer to the current file when running compilers and file
utilities. Thus, if you define the macro
AltR compile_^F_/g_/r1 [Enter] [Esc]
the ^F embedded in the string will be expanded, so that the DOS command
executed by AltR when the macro is invoked will actually be something like
compile C:\PGM\MYPROG.C /g /r1.


EXAMPLES OF ^P NESTING. Note that in some situations, the use of ^P as a
prefix for control keys at the macro definition prompt becomes nested.
Suppose you want to define a macro containing the word "counterrevolutionary",
with "counter" italicized. The keystrokes you need to execute are:
^P^Ycounter^P^Yrevolutionary
but to get these into a macro definition, you must type ^P TWICE to enter each
^P (otherwise, ^P^Y will enter only the ^Y, which would delete a line!):
Macro: ...^PP^Ycounter^PP^Yrevolutionary...
Or, suppose you want to find the next occurrence of "Item" at the
beginning of a line. The actual keystrokes needed are:
^QF^PMItem^[Enter]
(Note the use of ^[Enter] instead of [Enter] to avoid the Options prompt.)
But to enter this as part of a macro definition, you will have to type:
Macro: ...^QF^PP^PMItem^P^[Enter]
Failure to nest ^P prefixes properly is one of the most common causes of
unexpected macro behavior.

TECHNICAL NOTE: Ordinarily macros are completely self-contained, and
NEVER request input from the keyboard while executing (unless the input pause
commands Esc? or Esc: are used). Even confirmation prompts like "Abandon
changes (Y/N)?", which may or may not pop up in normal usage of commands
affecting disk files, NEVER occur when a macro is running, so never include a
confirming "Y". But there is one exception: using AltR to run another program
(or DOS shell) from a macro is tricky. Any input requested by the program or
shell must be typed by you -- it cannot be included in the macro. (VDE
resumes control only when the program or shell terminates; if the macro
continues, its next keystroke must be the [Esc] required to return to
editing.)


---------------------------- C. RECORDING MACROS -----------------------------


As an alternative to composing macros and using the Esc[ command to
define them, you can simply record a macro as you go about a task. The main
advantages are that you can see the effects as you go, and none of the
additional ^P keystrokes sometimes necessary for entering commands at the
macro definition prompt will be needed. (On the other hand, a recorded macro
must be a simple series of keystrokes; it cannot contain programming commands
like jumps and tests.)

Just press Esc" to activate recording; type away; and press Esc" again to
conclude. You will then be asked whether to use or store the macro you have
created, just as if you had entered the macro at the Esc[ prompt.
While recording, a quote mark (") will be visible in the upper right
(prefix) area of the header. If you make an error while recording, use Esc"
to stop recording, press [Esc] at the prompt to quit, and start over.

NOTES: Because macros don't nest, Function key commands themselves (and
also the {User:} MenuBar) cannot be used while macro recording is in progress.
Any other keystrokes can be recorded, including all other MenuBar selections.
Be careful when creating macros by recording [BkSp], [Del], [Home], or
[End]; the functions of these keys are VINST options and may differ in someone
else's copy of VDE, so you may wish to use command equivalents like ^S, ^G,
^QS, ^QD instead.


------------------------ D. ASSIGNING MACROS TO KEYS -------------------------


Up to 48 macros can be assigned to function keys; they can then be
recalled and used with one keystroke. Each PC function key can be used alone
or with Shift, Ctrl, or Alt, to produce:
[F1]...[F10] = F1....F10 in VDE notation
Shift-[F1]...[F10] = !F1..!F10
Ctrl-[F1]...[F10] = ^F1..^F10
Alt-[F1]...[F10] = @F1..@F10
And, if you have an Enhanced (101-key) AT keyboard, also:
F11, F12, !F11, !F12, ^F11, ^F12, @F11, @F12
VDE comes with [F1] set as a "Help" key (^J), but this can be changed.

For those who find function keys difficult to remember, you can also
assign a letter or digit to invoke a definition with the [Esc] key; thus, if
your Address is on [^F3], you could also call it up with EscA.

The Esc[ command (see MACRO DEFINITION) gives the option of Storing the
macro definition to any function key, so that the macro can later be executed
simply by pressing that key. If you choose "Store",
VDE asks "Make Quiet, No-repeat, Both:". Reply "Q" for
a key that executes in Quiet (fast) mode; "N" for a key
that runs once, without asking for a repeat count; or "B"
for both of these. Press [Enter] instead for a key that
executes just like the "Use macro" option, visibly, asking
for a repeat count first.
VDE asks "Store to key:". Press the desired function
key, from [F1] to [@F12].
VDE asks "Esc key:". If desired, press a letter or
digit, which can then also be used with [Esc] to invoke
this key.
VDE asks "Label?" Enter a label, up to 7 characters,
for the key label line (see FUNCTION KEY LABELS).

Don't choose "Q"uiet (or "B"oth) for a key that will request input from
you. There are about 2000 bytes of storage available for all 48 keys, and a
125 byte limit [in VDE; VINST can accept 253] for any one key. You can delete
a key definition by entering a null macro string (Esc[, [Enter]) and storing
it to the key. Pressing an undefined key gives an error.
Keys defined while editing in VDE last only during the current editing
session. [To add a function key permanently to VDE.EXE, use VINST: either
enter it again in VINST, or write it to a file and read the file into VINST --
see DEFAULT FUNCTION KEYS and DATA FILES.]


---------------------------- E. MACRO PROGRAMMING ----------------------------


"Macro programming" refers to a group of VDE commands that operate only
within a macro definition, and give you conditional control over the execution
of a macro. Thus, instead of simply running straight through a sequence of
keystrokes, a macro can be constructed very much like a computer program, with
conditional or unconditional jumps from one part of the macro to another,
giving great flexibility and power. Here is a brief introduction to the range
of macro programming commands.

Jumps require "labels" to identify where to jump to. VDE labels consist
of [Esc] followed by a letter A-Z or digit 0-9. If you typed this from the
keyboard, it would be interpreted as an attempt to invoke a function key
definition by an alias (see FUNCTION KEYS) -- but in a macro, there is no
effect: it simply identifies a location in the macro.

Esc! is the unconditional jump instruction. Followed by A-Z or 0-9, it
causes execution of the macro to transfer to the command following that label,
instead of simply continuing as usual to the next command. So, for example,
Esc!1 jumps to the label Esc1. Thus the macro:

This_is_ Esc!1 not_ Esc1 a_silly_macro.

would produce the text "This is a silly macro." In contrast, the macro:

This_is_ Esc1 not_ Esc!1 a_silly_macro.

would produce "This is not not not not not not not not not....", continuing
indefinitely until you press [Esc] to abort it. (This is an example of what
programmers call an "infinite loop" -- occasionally useful, but generally an
unfortunate error!)
There are also two special predefined "labels": "[" indicates the
beginning of the macro, and "]" the end. Thus Esc![ can be used to repeat the
macro from the start, and Esc!] can be used to terminate it from any point.

Several commands allow the use of a counter variable. Esc() sets the
value: for example, Esc(0) initializes it to zero. The Esc+ command simply
increments the value; Esc- (minus) is a conditional jump, decrementing the
value, then jumping if it is zero to the specified label. (In addition to a
label 0-Z, you may use "[" or "]", or "@" to avoid jumping entirely.)
Examples: Esc-] decrements the counter, jumping to the end (exiting) if it
reaches zero; Esc-@ simply decrements it, with no jump. Thus the macro:

This_is_a_ Esc(3) EscL silly_ Esc-L macro.

will produce the text "This is a silly silly silly macro."

Conditional jumps, or tests, are performed by Esc= and Esc~. Followed by
a character, then a label, they are conditional jumps: they jump IF the text
character at the cursor does (or for "~", does NOT) match the one specified.
Examples: Esc~_2 jumps to label 2 if the cursor character is NOT a space;
Esc=^M] jumps to the end (terminates) if the cursor character is a CR (^M).
Similarly, Esc< and Esc> test the cursor character's ASCII value and act
accordingly: thus Esc less than ASCII "A" (41 hex), etc.

The test commands (Esc=,~,<,>) can also be used in a second way, as self-
contained search loops. If instead of a label you use the character ">" or
"<", the command will move the cursor right (or for "<", left) as long as the
character at the cursor does (or for "~", does NOT) match the one specified.
Example: Esc=_> moves right as long as the current character is a space (so it
stops on the first NONspace). Of course you could have done the same thing by
programming an actual loop, with labels and a test and a right arrow command:

Esc1 Esc~_2 ^D Esc!1 Esc2

but Esc=_> is simpler and more convenient.

It is possible for one macro to chain (jump) to, or call, another macro.
This can permit construction of a single macro longer than the usual maximum
size; also, it often simply allows you to organize macros more efficiently and
conserve definition space. Esc&, followed by a key identification like "!F1",
is used to chain to another key; the macro terminates when that key finishes.
Esc&& works similarly, but calls the other key, so that when it finishes,
control returns to the original macro at the point following the Esc&&
command.


------------------------ F. EXAMPLES OF USEFUL MACROS ------------------------


Remember that macro examples are given as they function, NOT including
the occasional ^P prefix you will need to enter certain control codes like ^M;
and that while keystrokes are often separated by spaces for clarity, the
underline symbol "_" is used to represent an actual space that you must type.


SIMPLE MACRO EXAMPLES

1. At its simplest, a function key is a way to reproduce keystrokes.
Thus, if you're writing a document that will refer to "World Wide Widgets Ltd.
(N.A.)" dozens of times, it will be easier (and cause fewer typos) if you
define this phrase as a macro and assign it to a function key like [F3].

2. The macro repeat count is an easy way to repeat VDE commands. Suppose
you have a horizontal bar installed as graphic character "Y", and you need to
enter a line of 70 of them. You could press AltG, then Y, 70 times... or you
could define the macro: AltG Y
and then Use it with a repeat count of 70.
Similarly, to reformat an entire file, go to the top if necessary, then
at the macro prompt, just enter: ^B
Specify Quiet and indefinite repeat as options ("Q,*"). It will stop when it
reaches the end of the file.

3. To view a file by scrolling slowly through it, use the macro:
Esc; ^Z or Esc; ^C
This pauses, then scrolls down (a line at a time with ^Z, a screen at a time
with ^C). Don't make it Quiet, just use a repeat count of "*". Press [Esc]
when you want to stop.

4. This macro, with repeat count "*", would take all phrases in square
brackets "[]" found in a file, and make a list of them in a second file being
edited concurrently:
^QR ^QF[^J ^G ^KB ^QF]^J ^G ^KK AltC AltN AltP [Enter] AltB


SIMPLE FUNCTION KEY EXAMPLES

1. This macro, which could be stored as No-repeat on a function key, re-
loads the current file, eliminating any changes made since it was last saved:
^KL ^F [Enter]

2. A function key defined as ^QR ^N AltD ^OF would place the current date
at the top right of a letter. Many VDE users set up a function key to produce
a personalized letterhead: for example, the macro
^N John_Doe ^OC ^N 123_Main_St ^OC ^N City,_State ^OC
will insert that three-line address, neatly centered. You can add print
effects (bold, italic) to suit your taste. For a solid line separating this
from the body of the letter, try adding onto the end: ^N ^PS ^OF ^E ^PS ^X

3. Function keys can be used to create powerful new commands, for
example: ^D ^A ^KB ^F ^KK marks the current word as a block. And, similarly,
^QS ^KB ^X ^KK marks the current line as a block.


MACRO PROGRAMMING EXAMPLES

1. This macro moves to the start of the current paragraph:
^QS ^S^S Esc=_[ ^D^D
Like the rest of the examples in this section, it might best be stored Quiet,
No-Repeat to a function key.

2. Moving to the start of the current sentence is a bit more complicated,
but here is a macro program to do it:
Esc~.1 ^S Esc1 Esc~.< ^D Esc=_2 Esc=^M2 ^S^S Esc!1 Esc2 ^D Esc=_2 Esc=^M2
You could explain this in programmer's pseudo-code as:
If not "." goto label1 ;move left if already on period
Move left
label1: While not "." move left ;move left to previous period
Move right ;move right to following character
If " " or ^M goto label2
Move left twice ;skip over a period if it's not
Goto label1 ; followed by a space or return
label2: Move right ;okay, now move right as long
If " " or ^M goto label2 ; as you see a space or return
(all done)

3. If you have some text that you can't reformat because every line ends
in HARD CRs, this key will "soften up" the current paragraph, leaving just one
HARD CR at the end: ^QS ^X Esc=_] Esc=^M] ^S_^D Esc![
(Note that this requires paragraphs to have first-line indents or a blank line
betwen each of them.)

4. If you want to produce a "pure ASCII" file for software that can't
accept control codes (other than CR,LF) or IBM graphics, here is a key
definition that will filter these out before you save to disk (use filemodes
/A,U,N): Esc*f EscB Esc>~X Esc=^MN Esc<_X EscN ^D Esc!B EscX ^G Esc!B

5. This macro moves the cursor to the center of the current line; note
how the counter variable is used to figure the line length, then move back
only halfway: ^QS Esc(0) Esc1 Esc+ ^D Esc~^M1 Esc2 Esc-] Esc-] ^S Esc!2

6. Many programming languages use nested sets of parentheses, for example
"{}" in C. This macro, when the cursor is placed on an open bracket "{", will
move ahead to find the closed bracket "}" that matches it:
Esc~{] Esc(0) Esc1 Esc~{2 Esc+ Esc!3 Esc2 Esc~}3 Esc-] Esc3 ^D Esc!1



============================= 9. MACRO REFERENCE =============================


AUTOEXEC MACRO - VINST can designate any function key definition you create
as "autoexec", meaning a macro that will execute automatically whenever
you first enter VDE. This feature can be used for a variety of purposes,
including changing defaults not available through VINST options. See also
FUNCTION KEYS.
Notes: if you load multiple files, remember that for settings which
are specific to each file (like margins), only the first file will be
affected. You cannot use a utility like KEYSTACK that stuffs input into
the DOS keyboard buffer before running VDE, if an autoexec macro exists.

CHAINING AND CALLING (Esc&,&&) - Esc&, followed by a key identification like
"!F1", is used to "chain" (or jump) to another function key. Use "!,^,@"
for Shift, Ctrl, Alt; and after the "F", a single digit "1"-"9", or "A"-
"C" for 10-12. ("0" is also accepted for F10.) Examples: Esc&F2 chains
to F2; Esc&^FB chains to Ctrl-F11.
Esc&& works similarly but "calls" the other key, returning when it
finishes. Calls may be nested at most 4 deep.

COUNTER VARIABLE (Esc(),+,-) - Esc(n) sets the counter value to "n". Esc+
simply increments the value; Esc- (minus) is a conditional jump,
decrementing the counter, then jumping if it is zero to a specified label.
(Besides a label 0-Z, you can use "[" or "]" for the start or end, or "@"
to decrement without jumping at all.)
The counter can run "negative", though it is actually an unsigned
integer: if you decrement it from 0, it becomes 65535 (effectively -1); if
you increment it from 65535, it becomes 0.

DEFINE OR RECORD MACRO (Esc[,") - To define a macro, type Esc[. You will be
asked for the macro definition; for full instructions, see DEFINING
MACROS. Once defined, you will have the option to Use the macro
immediately or to Store it to a key.
Even if you did not Store your last macro when you originally defined
it, you can still re-Use (or Store) it at a later time by using ^R
(replay) at the Esc[ prompt.
As an alternative to composing macros and using the Esc[ command to
type them in, you can simply record a macro as you go about a task. Press
Esc" to activate recording; type away; then press Esc" again to conclude.
While recording, a quote mark (") will be visible in the upper right
(prefix) area of the header. If you make an error while recording, use
Esc" to stop recording, press [Esc] at the prompt to quit, and start over.

ERROR HANDLING (Esc$) - Esc$ can specify a label where macro execution should
continue if an error occurs (normally, execution would terminate). Thus,
after the command Esc$E, any command resulting in an error (like "Not
Found") will cause a jump to label E, ignoring the error. You can also
use the special characters "[","]" to jump to the beginning or end of the
macro, or "@" to simply ignore errors, not jumping anywhere, or "$" to
return to the normal default of halting on any error.

FUNCTION KEYS ([F1]...[F12], EscA-Z,0-9) - Macros can be assigned to function
keys, either alone or with Shift, Ctrl, or Alt (!,^,@) for a total of 48
function keys. These keys can be labeled for easy remembering (see
FUNCTION KEY LABELS), or you can assign a letter or digit to invoke a
definition with the [Esc] key; thus, if your Address is on [^F3], you
could also call it up with (say) EscA. For detailed instructions, see
ASSIGNING MACROS TO KEYS.
(Note: users of VDE prior to version 1.7 will recall EscA-Z as a
separately definable set of MACRO KEYS; they now function simply as
mnemonic aliases for function keys.)

FUNCTION KEY LABELS (^OU) - To help you remember the purpose of your function
key definitions, the ^OU command toggles the display of a label line at
the bottom of the screen. When a key is defined, its number will appear
on the label line, followed by the label (if any) entered when the key was
stored.
The label line is sensitive to keyboard shift status; if you press
and hold Shift, Ctrl, or Alt for a moment, the labels will change to show
those for the shifted function keys.
On 80-column screens, 10 labels are visible; in 40-column mode, 5.
Labels for the F11, F12 keys only appear on screens of 96 or more columns.

KEY DEFINITION FILES (AltU) - These files save function key definitions and
labels, and should be given a file type of ".VDF". You can load such a
file, along with your text file(s) to edit, from the command line (see
SYNTAX).
AltU can be used while editing: it will ask whether you want to
"L"oad or "S"ave such a file, then prompt for the name of the file. If
you load a .VDF file, those definitions will replace any previous ones.
If you save, the current definitions will be written to the file. [.VDF
files can also be created or installed as defaults in your copy of VDE,
using VINST.]

LABELS AND JUMPS (Esc0..Z,Esc!) - Esc0..Z, when placed in a macro, function
simply as local "labels" 0..Z. They have no effect, but can be "jumped"
to by other commands.
Esc! followed by 0..9,A..Z is a "jump" instruction, causing macro
execution to resume with the command following that label. Example: Esc!2
jumps to label 2. As two special cases, Esc![ jumps to the beginning of
the macro, and Esc!] jumps to the end (exits).
Note that Labels can also be referenced by the test commands, which
perform conditional jumps (see TESTS AND LOOPS).

PAUSE (Esc;,Esc?,Esc:) - Esc; gives a brief pause before macro execution
continues, so the user can see what's happening on screen. Use two or
more to get a longer pause.
Esc? accepts text or commands from the keyboard during macro
execution. The header's "!" flag turns into "?" when user input is
expected. Anything except macro and function key commands may be used.
[Esc] terminates input, returning control to the macro. ^[Break] aborts.
Esc: makes the following command take its input from the keyboard.
The macro resumes when that command is completed. Examples: Esc:^QF
allows you to type in the string to find; Esc:Esc! actually lets you type
the label to jump to.

TESTS AND LOOPS (Esc=,~,<,>) - Esc= and Esc~ perform tests on the character at
the current cursor position. There are two ways to use them:
(1) Followed by a character, then a label (0-Z,[,]),
they are conditional jumps: they jump to the label IF the
cursor character does (or for "~", does NOT) match the one
specified.
(2) Followed by a character, then ">" or "<", they are
search loops. They will continue to move the cursor right
or left as long as the cursor character does (or for "~",
does NOT) match.
Similarly, Esc< and Esc> test the cursor character's ASCII value and
act according to whether it is less, or greater, than the specified value.
(See ASCII table in VINST.REF)
(Note: place and block markers, since they are not part of the file
text, will fail any test. If you need to check for their presence, you
can use Esc<^@ [that's 00 hex, entered as ^P@] since no actual character
could be <0 and fail this test.)

TOGGLE CONTROL (Esc*) - "Toggle" commands can create difficulties when used
in macro and function keys: ^V, for example, toggles insert mode. But
when you plan a function key, you don't necessarily know how Insert will
be set when the key is used! So if you use ^V in the macro, you don't
know whether you just turned it off or on; you might be overstriking or
inserting, and can't tell.
The Esc* command provides a solution, by letting a macro specify an
exact state for each toggle. Esc* must be followed by a LETTER to
identify a toggle, UPPERcase to turn it ON or LOWERcase to turn it OFF.
(Insert and Justify each have a third state, as well.) For example, Esc*i
will set INSERT OFF, regardless of its previous state. The toggles are:
Autoindent (^OA) 'a'=off 'A'=on
Doublespace (^OS) 'd'=off 'D'=on
auto Format (^OM) 'f'=off 'F'=on
Hyphenation (^OH) 'h'=off 'H'=on
Insert (^V) 'i'=off 'I'=on 'W'=word
Justification (^OJ) 'j'=off 'J'=on 'R'=remove
Proportional (^OK) 'p'=off 'P'=on
Varitab (^OV) 'v'=off 'V'=on
margin release (^OX) 'x'=off 'X'=on



==============================[end VMACRO.REF]================================