Documentation for "ANDY's MACROS"
Text Boxing Macros
for WordStar Release 5 Users

(C)1989 A.BARBOLLA
250 Governors Drive, Suite G
Huntsville, AL 35801

A Shareware Product
Macro Revision 2.0
Documentation Revision 021289


--------
OVERVIEW
--------

This group of macros and support files, collectively called
ANDY's MACROS, provides automated single and double line boxing
capability, among other features, to WordStar Release 5 users.
By simply pressing one of the newly redefined macro keys, sen-
tences and paragraphs can be automatically boxed-in with single
line characters and then centered automatically. Box sizes are
key selectable at 15, 25, 35, 45, and 55 characters wide. Another
macro key will allow any box, with or without text in it, to be
automatically changed from single line to double line within a
few moments. I use each of these macros daily in writing tech-
nical manuals for my company and they have proved to be an in-
credible time saver for me. Of course, any of the macros may be
redefined if you desire. You can easily mix the box-producing
macros with your own favorite macros to come up with a personal-
ized hybrid version of ANDY's MACROS.



----------------
SHAREWARE NOTICE
----------------

This product may not be sold without written permission from the
author. It can be copied and distributed providing that all
files are included, and that they are unchanged in any way.

This group of files was produced specifically for release as a
copyrighted Shareware product. Although it may seem unusual to
offer a non-stand-alone product as a Shareware release, ANDY's
MACROS represents a commercially useful productivity tool for
WordStar 5 users. A great deal of my personal time has gone into
creating, perfecting, and thoroughly debugging these macros. In
fact, most of my time has been spent on the documentation,
preparation, and final polishing of the product for release as
Shareware. Therefore if you find this product to be even occa-
sionally useful, I am encouraging you to please send a small $5
registration fee.

For your $5 dollars I will register you as a product user, and
inform you of ANDY'S MACROS upgrades, as well as future Share-
ware products that will make your WordStar 5 editing sessions
more productive. In addition, I will attempt to provide limited
phone support for those folks who need help in getting their
ANDY's MACROS running, or who have questions regarding how addi-
tional custom macros may be constructed using the macro-chaining
and macro-subroutines techniques.

ANDY's MACROS are constantly evolving and improving, therefore,
if you include a self-addressed stamped disk mailer along with
your registration fee I will send you the latest version of
ANDY's MACROS with complete documentation on a 5 1/4" IBM compat-
ible floppy disk.

Send registration fee to:

Andy Barbolla
250 Governors Drive, Suite G
Huntsville, AL 35801

(CompuServe - 73107,1177 and 71160,1632)





------------------
SYSTEM ASSUMPTIONS
------------------

It is assumed that the ANDY's MACROS user has the following
computer system configuration:

1) IBM Compatible Computer with WordStar Release 5 installed
and properly running from a hard disk drive.

2) WordStar is running on drive C: in subdirectory \WS5.


Note: If item 2 is not true, a simple modification to the
support file DOS.BAT may be needed. This procedure is
described later. In addition, all references in this
document to "C:\WS5" should be represented by the
particular drive and directory where WordStar resides
on your hard disk drive.



----------
THE MACROS
----------

The following is a summary of ANDY's MACROS. The number or
letter in the left column represents the macro key that must be
pressed after hitting the ESCape key. This first group of macros
contains the more "elegant" ones:

1 Box a sentence or paragraph Box size: 15 characters wide
2 Box a sentence or paragraph Box size: 25 characters wide
3 Box a sentence or paragraph Box size: 35 characters wide
4 Box a sentence or paragraph Box size: 45 characters wide
5 Box a sentence or paragraph Box size: 55 characters wide
H Hi-lite next BOX to double line
O Up-case word
L Low-case word
D DOS access from Editor
Q DOS access from Main Menu


These next macros are more on the order of the generic/utility
variety. They represent my own particular preference and can
easily be changed to your own inclinations:

A Align & Wordwrap ON/OFF
B Bold Text ON/OFF
C Center Text
E Extended Characters
F Font Selection
I Italics ON/OFF
M Math Calculator
P Print Controls ^OD Toggle
R Abort and then Restore current Document
S draw Square
T Transpose Word
U Underline
V preView Document
W Window Open/Switch


The macros below are used as continuations and subroutines of the
major BOX macro routines listed above and should not be redefined
by the user. They should also never be used as stand-alone
macros (don't hit them accidentally either) as erratic results
will definitely occur.

0 macro 1 - 5 continued
6 macro 1 - 5 continued
7 macro 1 - 5 continued
8 macro 1 - 4 subroutine
9 macro 1 - 4 subroutine
J macro H continued
X macro H subroutine
Y macro 5 subroutine
Z macro H subroutine



--------------
REQUIRED FILES
--------------

The following ANDY's MACROS files are contained in the original
archive file which is named WS5MACRO.ARC (WS5BOX.ARC on Compu-
Serve):

WS5MACRO.DOC This documentation file
WSSHORT.0-1 Custom macros for help levels of 0 to 1
WSSHORT.2-4 Custom macros for help levels of 2 to 4
B1.OVR BOX template Width: 15 characters
B2.OVR " " 25 " "
B3.OVR " " 35 " "
B4.OVR " " 45 " "
B5.OVR " " 55 " "
DOS.BAT Called by macro D and Q. Allows complete
DOS access from WS5.

The above files, except for the .DOC file, are needed for proper
operation. Once installed, all files must be made available to
WordStar in the current WordStar directory (which is usually
\WS5).



----------------------------------------------------
TRANSFERRING THE MACROS TO THE WORDSTAR SUBDIRECTORY
----------------------------------------------------

You must have already unarchived WS5MACRO.ARC, in order to be
reading this DOC file. If this DOC is posted separately, and you
must still unarchive WS5MACRO.ARC, use PKXARC.COM (or equivalent)
and type PKXARC WS5MACRO. When the archive dissolves, the 9
ANDY's MACROS files mentioned above will be present in the cur-
rent directory.

Once the files are extracted from the archive, they may be copied
from their present location to the WordStar subdirectory. Obvi-
ously if you have dissolved the archive in your WordStar directo-
ry you will not have to use the following COPY commands.

Type the following commands pressing Return after each line:

COPY WS5MACRO.DOC C:\WS5
COPY WSSHORT.* C:\WS5
COPY B?.OVR C:\WS5
COPY DOS.BAT C:\WS5



------------------------------------
SETTING UP WORDSTAR 5 FOR THE MACROS
------------------------------------

Before using ANDY's MACROS two things must be done.

The first is to preserve your old macros in case you wish to use
them again at a later date. This is done simply by renaming your
original macro file to another name. Also, depending on your
particular WordStar Help Level, the appropriate ANDY'S MACROS
file must be copied to WSSHORT.OVR. This procedure is explained
below.

The second is a very minor change to WordStar that is required to
accommodate the large number of programmed commands in each
macro. It is a simple change to WS.EXE using the WSCHANGE pro-
gram. WSCHANGE is a WordStar support file that should already be
present in your WordStar subdirectory. Below is a step-by-step
procedure for making this change. If you are unfamiliar with
using WSCHANGE, don't panic. The procedure below will walk you
through painlessly. Also, if you get lost, you can instantly
abort WSCHANGE and restore WordStar to its previous settings by
pressing the CONTROL key and the C key at any time.


STEP-BY-STEP PROCEDURE FOR PRESERVING YOUR ORIGINAL MACRO FILE
AND INSTALLING ANDY'S MACROS:

1) Get into the WordStar subdirectory. This can be done by
typing the DOS command: CD C:\WS5 and pressing the Return
key.

2) Type REN WSSHORT.OVR WSSHORT.OLD and hit Return.
(You have just preserved your old macros under the name
WSSHORT.OLD. If you ever wish to use them again you can
rename any current macro file to another name by doing: REN
WSSHORT.OVR WSSHORT.SAV for example, and then rename your
old macro file WSSHORT.OLD back to WSSHORT.OVR.)

3) Type the following commands depending the WordStar Help
Level that you are currently using:

Wordstar help level of 0 TO 1:

COPY WSSHORT.0-1 WSSHORT.OVR

Wordstar help level of 2 TO 4:

COPY WSSHORT.2-4 WSSHORT.OVR



STEP-BY-STEP MINOR CHANGE PROCEDURE TO WORDSTAR:

1) Get into the WordStar subdirectory. This can be done by
typing the DOS command: CD C:\WS5 and pressing the Return
key.

2) Type WSCHANGE and hit Return. Then type WS and hit Return
two times.

3) Type these keys exactly as shown:
C C H 15 (hit Return) 2 A 1600 (hit Return) X X X Y

Note: when you get to the H keypress, the current Macro
Buffer value is displayed in the lower right hand message
box. Write down this number. Similarly, when you get to the
A keypress the current setting for the Undo Buffer is dis-
played. Write this down also. Should you ever desire to
return to your original settings, you can do so by following
steps 1 and 2 above and then typing:
C C H (MB) (hit Return) 2 A (UB) (hit Return) X X X Y
Where (MB) is the first number and (UB) is the second number
that you wrote down.

4) That's all there is to it. There is now plenty of room in
the macro buffer for not only the ANDY MACROS but quite a
few additional macros of your own design. The undo buffer
increase is required so that WordStar will not interrupt the
macros with a "Cannot undo later, continue Y/N? " message
which will throw the macros out of synchronization. This
prompt only occurs if the help level is set higher than 1.



-----------------
MACRO INFORMATION
-----------------

At this time the macros are ready to use. To try the macros
simply run WordStar just as you normally would. Initially it is
a very good idea to try these routines on an unimportant or a
sample document to get the feel for using each one.

Until you have absolute confidence in the macros, always save
the present state of your document before using the macros by
typing ^KS to save the current state of the document. This way,
should something go wrong, you will be able to restore back to
the last saved version of the document.



-------------------------------------
USING THE MACROS (AND MACRO CAUTIONS)
-------------------------------------

This section will give detailed operational information and
include some warnings on macro usage.

*--> ALL BOX MACROS ASSUME THE FOLLOWING:

1) THE COLUMN MODE (^KN) AND COLUMN REPLACE MODE
(^KN^KI) ARE **OFF**. This is the normal de-
fault when document is first loaded.
2) WORDWRAP (^OW) AND AUTO-ALIGN (^OA) ARE **ON**.
These are the normal defaults unless you have shut
them off either via WSCHANGE or by using the .aw
command.
3) PRINT CONTROL TOGGLES (^OD) ARE OFF. This is
required only if there are any embedded print
commands (^B - bold print, ^S - underline, etc.)
in the text that is going to be to be boxed. The
normal default is ON, therefore you must turn them
off by using ^OD or by changing the default set-
ting via WSCHANGE.
4) PROPORTIONAL FONTS SHOULD NOT BE USED WHEN BOXING
TEXT. If you have been using a PROPORTIONAL font
for your document, in order for the macros to work
properly you must use a NON-PROPORTIONAL font at
the beginning of the text that is going to be
boxed. You can change the font with the ^P?
command, or use the F macro. After the macro has
executed and the text is boxed, return to your
original PROPORTIONAL font AFTER the text box.

It is important that the above modes are adhered to before any
BOX related macros are executed.

WordStar macros do not allow any conditional comparisons, there-
fore they cannot be made fool-proof. It is the responsibility of
the user to make sure that the conditions are met prior to actual
activation of a macro.

For example, if you try to use a box macro and the Auto-align
Mode is off, or the Column Mode is on, you will most definitely
get erratic macro results. Another example: if you try to box a
paragraph that is too long, the reformatted text will make it
into the box but will "fall through" the bottom. The rest of the
macro routine will lose its place and may accidentally delete a
few lines of your text. (This is easily changed - you can box a
page or two if you want - read on.) Once again, until you have
absolute confidence in the macros, always save the present state
of your document before using the macros by using the ^KS com-
mand. This way, should something go wrong, you will be able to
restore back to the last saved version of the document.

Assuming that you are using the standard page width of 65 charac-
ters the following statements will be valid:

1) The 15 character box is capable of boxing up to approximate-
ly 7 (65 character) lines for a total of 35 lines of 15
characters.
2) The 25 character box is capable of boxing up to approximate-
ly 10 (65 character) lines for a total of 30 lines of 25
characters.
3) The 35 character box is capable of boxing up to approximate-
ly 12 (65 character) lines for a total of 25 lines of 35
characters.
4) The 45 character box is capable of boxing up to approximate-
ly 16 (65 character) lines for a total of 25 lines of 45
characters.
5) The 55 character box is capable of boxing up to approximate-
ly 20 (65 character) lines for a total of 25 lines of 55
characters.

The number of text lines that any of the boxes will handle can
easily be increased by simply editing the box-template files,
B1.OVR, B2.OVR, B3.OVR, B4.OVR, and B5.OVR. These files have
an .OVR extension only so that they do not show up on the Opening
Menu directory, however, they are completely normal document
files. By loading them in as a Document and using the copy
command on a line in the middle portion of the box, these tem-
plates can be made as long as you wish. Please note that the
longer the box, the longer time the command takes to execute.
Also, if you are using a help level greater than one, you will
have to increase the Undo Buffer even further to stop WordStar
from issuing a confirmation prompt which makes the macros lose
their place. Refer back to the "Setting Up WordStar" section and
change the 1600 value to 2500 or 3500 depending on how much
larger your box templates are.



--------------
THE BOX MACROS
--------------

Box Macros as displayed on the SHORTHAND MENU:

1 Box Text (must end in Return) Size:15 Max 7 lines of 65 chars.
2 Box Text (must end in Return) Size:25 Max 10 lines of 65 chars.
3 Box Text (must end in Return) Size:35 Max 12 lines of 65 chars.
4 Box Text (must end in Return) Size:45 Max 16 lines of 65 chars.
5 Box Text (must end in Return) Size:55 Max 20 lines of 65 chars.

Using macros 1 through 5 is pretty simple. Keeping in mind the
warnings above, just place the cursor on the line that your
sentence or paragraph is on and make sure the cursor is against
the left margin. Then press the ESCape key and the macro key for
the size box desired. Within about 10 - 30 seconds your text
will be automatically boxed.

The text, whether it is a single sentence, or a paragraph, MUST
ALWAYS END IN A HARD RETURN. This means you must press the
Return key at the end of your sentence or paragraph in order for
the macro to work correctly. This is really nothing new, press-
ing Return is normally done to end a paragraph anyway.



------------------
THE SUPPORT MACROS
------------------

Support Macros as displayed on the SHORTHAND MENU:

H Hi-lite BOX to double line
O Up-case word
L Low-case word
D DOS access from Editor
Q DOS access from Main Menu

The H macro allows you to "Hi-lite" the very next single line box
into a double line box regardless of whether or not there is text
in it. Place the cursor anywhere BEFORE the box to be Hi-lited
and press the ESCape key and then the H key. This macro is
rather tricky, it even creates a temporary workspace at the end
of your document, but eventually it gets the job done (sure beats
doing it manually). Because of the temporary workspace, the time
it takes to do the job is directly proportional to the distance
from the box to the end of your document. The longer the dis-
tance, the longer the macro will take.

THIS PROCEDURE MAY TAKE QUITE SOME TIME, OBSERVE THE WORDSTAR
"WAIT" MESSAGE IN THE UPPER LEFT CORNER OF THE STATUS LINE.

Note: you may find a few extra carriage returns at the end of
your document. This is caused by the workspace usage. If you
have Hi-lited a very large box or many smaller ones you may wish
to go to the end of the document and delete the extraneous re-
turns.

The O and L macros do just what the name implies, they change all
the characters in the word at the cursor to upper or lower case.
If you've ever tried writing upper or lower case macros yourself,
you already know that it is a real problem getting the macros to
work under all conditions. This is caused by the unknown charac-
teristics of the block markers present position within the docu-
ment and/or block marker hide status. Well, these macros will
work regardless of the current status or position of the block
markers. In addition, you can quickly do a sentence or two by
repeatedly using these macros because the cursor is automatically
positioned on the next word.

The D and Q macros automatically execute DOS.BAT which loads in a
command processor to provide a "DOS GATEWAY". This gateway
allows you to execute any DOS commands or run other programs
provided your computer has enough memory left (WordStar remains
in memory). You must type EXIT to return to WordStar. It
doesn't matter what subdirectory or drive was accessed, DOS.BAT
will always return you to the C:\WS5 subdirectory. Press ESCape
D from within a document, and ESCape Q when at the Opening Menu
to access the DOS Gateway.

Note: if you are not using drive C: or \WS5 as your WordStar
subdirectory, then the file DOS.BAT must be edited in the NON-
Document mode to reflect the appropriate drive and path. Change
all occurrences of C: and C:\WS5 to the drive and path you are
using.



------------------
THE UTILITY MACROS
------------------

Utility Macros as displayed on the SHORTHAND MENU:

A Align & Wordwrap ON/OFF
B Bold Text ON/OFF
C Center Text
E Extended Characters
F Font Selection
I Italics ON/OFF
M Math Calculator
P Print Controls ^OD Toggle
R Abort and then Restore current Document
S draw Square
T Transpose Word
U Underline
V preView Document
W Window Open/Switch


The above macros are all pretty much self explanatory, except for
the R macro. The R macro (Abort and Restore macro) essentially
means that the document you are currently editing will be totally
abandoned without further notice and the last saved version of
that same document will be immediately reloaded. The cursor will
be positioned in the same approximate region that it was in the
abandoned document.

NOTE: THE R MACRO WILL NOT WORK PROPERLY FROM A WINDOW.

This command can be somewhat dangerous if you accidentally hit
the macro and haven't saved your document in a while, so be
careful. I find it quite useful when experimenting with document
margins, text placements, and such. If I really mess up the
document I'm working on, my last saved version is only a key-
stroke away. NOTE: if you have opened a window anytime prior to
using the R macro, you will abort your current document as men-
tioned above. However, instead of reopening your current docu-
ment, you will find yourself in the document that was last opened
in the window. If this happens simply use ^KQ to abort back to
the opening menu and reopen your original file.



---------------------
QUESTIONS AND ANSWERS
---------------------


Q. Can I use the box macros on a blank line?
A. Yes, you will get a shortened box that is centered within
your margins. It can be made larger by blocking the middle
section and copying it repeatedly. In addition, you can box
a word or two and then manually center the word(s) for
titles, etc. The box will not reformat because each line
ends in a hard return.

Q. The macros don't seem to work when I am in a subdirectory
other than \WS5. How can I use the macros in a different
subdirectory?
A. The easiest way to do this is to copy all of the overlay
files into any subdirectories that you will be using with
WordStar.

Use the following command:
COPY \WS5\B?.OVR \"name of directory"

If the subdirectory is under the WS5 directory then:
COPY \WS5\B?.OVR \WS5\"name of subdirectory"

In addition, in order to use the Esc Q and D macros, you
must also copy the DOS.BAT file into each of your subdirec-
tories. Then the last line of DOS.BAT must be modified
(non-document mode) to set the return path back to the
particular subdirectory.

EXAMPLE DOS.BAT:

echo off
cls
echo WordStar<>DOS Gateway. Type 'EXIT' to return to Wordstar.
%comspec%
c: <- add the drive where WS5 resides
cd\"name of directory" <- add the directory where WS5 is


Q. Some macros appear to be blank. Is this normal?
A. Yes, the box macros call on these "blank" macros to accu-
rately measure the text column width.

Q. I can't seem to get the Hi-lite macro (Esc H) to work.
A. Esc H should be working for you. Here are a few tips: a) it
can only be used if a single line box has already been drawn
somewhere later in the document (i.e. further down from the
current cursor position), b) the cursor must be physically
positioned BEFORE the box to be Hi-lited, c) make sure that
you are using the appropriate version of ANDY'S MACROS for
your current Help Level.

Q. Why are there different versions of ANDY'S MACROS for dif-
ferent WordStar Help Levels?
A. WordStar macros, although straightforward and easy to pro-
gram, are somewhat primitive in that they do not provide for
any conditional branches. This means that the macro cannot
test the Align Mode, or the Column Mode, or the Help Level,
etc., etc., to tell what its current setting is and act
accordingly for each condition. That is the main reason the
user must manually meet certain conditions prior to activat-
ing the macro. This is also the reason that two versions
are required. The higher help levels prompt the user to hit
the escape key when finished with a find and replace. This
must be taken into account by the macros. Actually, the
only macro that is affected by the help levels is the H
macro. Therefore it is possible to switch to a different
help level and still use all of the macros except H.



-------------
CLOSING NOTES
-------------

I hope ANDY's MACROS makes your WordStar editing sessions a
little more productive and a little less tedious, as they have
definitely done for me. Comments, suggestions, bug reports,
etc., are always welcome.



----------------
REVISION HISTORY
----------------

Revision 2.0: Added a one character margin inside all box sizes
for better text appearance. Used %comspec% in DOS.BAT to make
use of DOS's comspec environmental variable for path information
to COMMAND.COM processor. Generally updated documentation and
added new mailing address.

Revision 1.0D: Modified macros 1 through 5 to provide for ^Q~
auto-insert mode. Added .rm command to last line of b1 - b5 box
templates.

Revision 1.0C: Changed the H macro to act inside the current
document instead of opening a window. Supplied two separate
macro overlay files named WSSHORT.0-1 and WSSHORT.2-4.

Revision 1.0B: The requirement of increasing the Undo Buffer to
1600 and Macro Buffer to 15 was added to the documentation.

Revision 1.0 and 1.0A: Original releases. Worked fairly well
but only for WordStar Help Levels of 0 or 1.



----------
DISCLAIMER
----------

The Author shall have no liability to any customer or user with
respect to loss, damage, or liability caused by this Package,
including but not limited to loss of data, interruption of serv-
ice, or loss of business or profits.
If you are sufficiently jolted by this disclaimer, we recommend
that you save all files before first loading the programs in this
package, and that you use them with care until you feel sure that
they will perform reliably in your machine.