Copyright (c) 1990, 1991
David Seidman
Software by Seidman
2737 Devonshire Pl. NW
Washington, DC 20008

January 4, 1991

                           MACROAID Version 1.1

INTRODUCTION

MacroAid is a shareware collection of DOS utility programs for use with
WordPerfect Corporation (WPCorp) program macros.  The programs work
with macros for WordPerfect 5.0 and 5.1, PlanPerfect 5.0 and 5.1,
DrawPerfect 1.0 and 1.1, ED 3.0, LetterPerfect 1.0, and Shell 3.0; they 
may work with later versions and other programs as well.  (They do not 
work with macros for the Windows version of WordPerfect.)  Several of 
these programs may be helpful to the casual user of macros, but 
MacroAid is primarily intended for the serious macro writer.  Writing 
WPCorp macros is computer programming, and  MacroAid is a set of 
programmer's tools. 

The shareware distribution consists of this documentation in ASCII text
file format (MacroAid.DOC), one or more MRQ files (described below),
seven application programs (MacArgs, MacAscii, MacCalls, MacCrush,
MacChang, MacFind, and MacRef), and MacShell, a program designed to
make the other programs easier to use in some circumstances. Users who
pay the license fee will also receive a file with this documentation in
WordPerfect format and additional MRQ files.  Other programs may be
added to MacroAid in the future; if so, they may be distributed only to
registered users.

Here are brief descriptions of the seven application programs:


MacArgs

Changes assignments to macro variables with DOS commands.  The DOS command

     MacArgs MyMacro.wpm -0Newstring -1AnotherString

changes

     {ASSIGN}0~OldString~{ASSIGN}1~stuff~

to

{ASSIGN}0~NewString~{ASSIGN}1~AnotherString~

in MyMacro.  Example uses: (1) write self-modifying macros that store
new information for later use, as for macros to number invoices
consecutively; (2) customize complex macros for different users.

MacAscii

Converts macros to ASCII text files or WordPerfect documents so that
they can be edited in WordPerfect or an ASCII text editor.  MacAscii
also converts the ASCII text file or WordPerfect document back to a
macro.  Allows editing of macros too big for the built-in macro editor;
editing of SH macros without WPCorp's ED editor; easy printing of
macros; use of powerful text processing and editing tools readily
available for ASCII text files.

MacCalls

Lists the files required by {CHAIN}, {NEST}, and {SHELL MACRO} commands
in a macro and the files required by these files.

MacCrush

Compresses macros by eliminating comments and the tabs and spaces used
only for formatting; replaces variable names and labels with two-
character names and labels.  Makes your macros load and, depending on 
which release of WPCorp's programs you are using, execute faster. 

MacChang

Changes the product type and version numbers stored within macros.
Changing your carefully developed WordPerfect macros to PlanPerfect
macros, for example, sometimes results in a working PlanPerfect macro
and should always at least make the conversion process easier.

MacFind

Searches for text strings, macro commands, and key commands in macros
specified with wildcard file specifications.

MacRef

Provides a cross-reference listing of a macro -- a file with a line-
numbered version of the text of the macro and a listing of each macro
command, key command, variable name, shell variable name, label, and
called file, with the line numbers on which each appears.  An essential
tool for the development and debugging of complex macros.



These programs run from the DOS command line.  The command line
parameters that control program operation are described below.
(Running the program from the DOS command line without any parameters
specified will produce a brief explanation of program usage.)  Because
these programs are not interactive, it is easy to use them in batch
files and to execute them from within macros.  Many people find it
difficult to use programs that depend on complex command-line
parameters.  MacShell provides another way to use the other seven
programs.  It prompts the user for the necessary command line
parameters, constructs the appropriate command line, and executes the
desired program, so that the user need not worry about the command line
details.  Even if you plan to use MacShell to run the other programs,
you should read the documentation for the other programs, so that you
will understand how they work and exactly what information MacShell
asks you to provide.

WordPerfect Corporation has no connection with these programs, except
that it provided much of the technical information necessary to writing
them.





                       Notes On Input and Output

Running any of the application programs generally requires supplying at
least one file name on the command line. Where no ambiguity is
possible, the program permits you simply to provide the filename.  More
often, you must identify the function of the file by a "switch" on the
command line.  For example, -ifname generally indicates that you want
to use file fname as an input file, and -ofname generally indicates
that you want to use file fname as an output file.  (You may always use
/ instead of - if you prefer.  The examples and illustrations here
sometimes use - and sometimes use /, to emphasize that you may use
either.)  The letter, e.g., i, may appear in upper or lower case.
Where switches are used, the order in which you list the files does not
matter.

Filenames on the command line may always include drive and path
specifications.  The individual program descriptions mention where
wildcards (* and ?) can be used.  Several programs supply default
extensions if you give a filename without an extension.  If a filename
should have no extension, you can avoid the default extension by ending
the filename with a period.

Some of these programs write their principal output to "standard
output" instead of to a file in the usual sense.  Other programs write
their principal output to a file, but also write some other output to
"standard output."  By default, standard output means the screen -- the
output goes to the screen in a continuous flow.  This may not be what
you want, either because more than one screen's worth of output will be
generated or because you want to keep or otherwise use the output.
Instead of letting standard output go directly to the screen, you can
"pipe" it to another program, or "redirect" it to either the printer or
a file.   The concepts of piping and redirection are explained in the
DOS manual.  Because many users of WPCorp products are not very
familiar with piping and redirection, we will provide examples below,
in the discussion of particular programs.  MacShell users can ignore
piping and redirection.



                                PROGRAMS


I.  MacArgs

MacArgs allows you to change the contents of a WPCorp macro from the
DOS command line.  It is not easy to explain exactly what MacArgs does,
or why it is useful, so this discussion will be a bit long and
complicated.  But bear with us -- MacArgs can indeed be very useful.
(The name of the program comes from the fact that some of what you can
use the program for resembles passing arguments to a macro.  If the
meaning of that is not clear to you, don't worry about it.)

The only parts of a macro MacArgs allows you to change are assignments
of values to variables 0 through 9, and only for one particular form of
such assignments.  That is, MacArgs works ONLY with macro statements
that look like this:

     {ASSIGN}0~string~

where what follows {ASSIGN} is a single digit.  MacArgs will, for
example, change string to NewString.  For any variable numbered from 0
to 9, MacArgs will change only the first assignment to that variable in
a macro.  It can, if you want, make changes for variables 0, 1, .. , 9
in a single run of the program.

Explaining why this is useful will be easier after you see how to run
the program.  It works like this:

     >MacArgs MacName -0Arg [-1Arg ... -9Arg]


(Note:  There is an alternative way to run MacArgs, discussed below.)

        MacName  Filename of the macro to modify.  Extension defaults
                 to wpm, but other extensions are accepted (including
                 drm, plm, edm, and shm).

        -0Arg    Arg is new string to assign to VAR 0

        -1Arg    Arg is new string to assign to VAR 1

                 [etc.]

         Args may appear in any order, and you may include as many or
         as few as you like.


     Restrictions:

     (1)  If any Arg includes blanks, that whole ARG must be enclosed
          in quotation marks (single or double), e.g., -0"Has a blank".

     (2)  Enclose Arg in single quotes (' only, not `') if it includes
          double quotes.  Enclose Arg in double quotes if it includes
          single quotes.

     (3)  Arg may not include |, >, or <.

     (4)  Each Arg is limited to 100 characters.

     (5)  The size of the macro is limited to 55,000 bytes.


(Note:  if you redirect the program output to NUL, no output will
appear on screen.  To do that, simply add >NUL to the end of the
command line.)


Example:

Suppose we have a macro MyMacro.WPM which contains, among other things,
the following:

          {ASSIGN}0~String0~
          {ASSIGN}5~String1~

Then

     >MacArgs MyMacro -0"This is the first assignment" -5Next>NUL

will change those two lines in the macro to this:

          {ASSIGN}0~This is the first assignment~
          {ASSIGN}5~Next~

without sending any output to the screen.


Applications:

Why do this?  There are many situations in which it could be useful.
Here are a few examples:

(1)  You want to call up WPerf from the DOS command line and have it
load the file you will edit.  But the file is an ASCII text file, and
either you are using WPerf 5.0, or you are using 5.1 but want hard
returns only at the ends of paragraphs.  You cannot simply type >WP
TheFile at the DOS command line, because 5.0 will not load an ascii
text file that way and 5.1 will put a hard return at the end of each
line.  You can use a startup macro, but how do you get the filename
into the macro?  With a batch file and MacArgs.  You need a macro
(LOAD.WPM) that looks like this (this one is for 5.0):

     {DISPLAY OFF}
     {ASSIGN}0~junk~
     {Text In/Out}13{VAR 0}{Enter}


Then you need a batch file (WPASC.BAT) like this:

     @echo off
     MacArgs Load -0%1
     wp/m-load

To load the ascii text file Text.Asc with hard returns only at the ends
of paragraphs, you would then invoke the batch file at the command
line:

     >WPASC Text.Asc

(2)  It is often useful to have a macro that keeps track of a number
and increments that number by one each time you use the macro.  You may
want to number your invoices consecutively.  Or you may want to name
files so that part of the name indicates the client and the rest is a
number.  There are lots of other examples.

Incrementing a variable within a macro is easy enough.  The problem is
that when you exit from WPerf, you lose the number stored in the
variable.  MacArgs allows you to store the number in the macro itself,
and, if you are using 5.1, the macro can actually modify itself to
store the new value of the variable.  That way, you can come back next
week, and the number will still be stored in the macro.  Here is a
fragment of a 5.1 macro that modifies itself to store the incremented
value of a number:

   File                COUNTER
   Description         increments and modifies itself

   {DISPLAY OFF}
   {ASSIGN}0~0~
   {;}Do something with variable 0 here~
   {ASSIGN}0~{VARIABLE}0~+1~
   {Shell}CMACARGSCOUNTER.WPM-0{VARIABLE}0~>NUL{Enter} A

The basic mechanism here can be extended quite far.  You could, for
example, use a single macro to keep track of the sequence numbering for
ten different basic file names.

(3) In an organization, it may be useful to distribute the same macro
to many different people -- but in a slightly different version for
each person.  Perhaps it is a macro that provides a complimentary close
to a letter, and the name has to be different for each letter writer.
MacArgs can help by allowing you to customize a basic macro.

As described so far, MacArgs is not very convenient for making
customized versions, because each time it runs, it modifies the input
macro without changing its name.  A different syntax for running
MacArgs, however, makes this kind of customization easy.  On the DOS
command line, you provide only a single file name, preceded by @:

   >MacArgs @fname

   fname is an ascii text file.  Each line of the ascii text file is in
   this form:

   InMacro OutMacro -0Arg [-1Arg ... -9Arg]

Used this way, MacArgs does not change InMacro at all.  It creates a
new macro, OutMacro, which is identical to InMacro except for the
modifications indicated on the rest of the line.


Writing Macros For Use With MacArgs:

In writing macros for use with MacArgs, it is a good idea to have all
the assignments you will want to modify at the beginning of the macro:

   {DISPLAY OFF}
   {ASSIGN}0~junk~
   {ASSIGN}1~junk~

and so forth.

MacArgs ignores any subsequent assignments to the same variables.
Collecting all the assignments you want to modify at the beginning of
the macro makes it easier to keep track of which assignment statements
are subject to modification.  (It also will make MacArgs run a few
microseconds faster.)

That MacArgs works only with variables 0-9 may seem confining if you
are using WPerf 5.1 (or another WPCorp product that allows named
variables), since MacArgs apparently forces you to use variables 0-9
throughout your macro to take advantage of its capabilities.  You can
get around this problem in the initial section of the macro.  Say you
would rather use the variable name FileName in your macro.  Do it this
way:

   {DISPLAY OFF}
   {ASSIGN}0~junk~
   {ASSIGN}FileName~{VAR 0}~

Then FileName has the information you want to use in the macro (and you
can go on to use variable 0 for any other purpose).


II.  MacAscii

MacAscii converts a WPCorp macro to a text representation of the macro
(in either WP5 document or ascii text file format); it also converts
text representations of macros (again, either WP5 documents or ascii 
text files) to macro files.  Roughly speaking, it is a macro compiler 
and decompiler.  It works with macros for all recent WPCorp products 
(WPerf beginning with 5.0, PlanPerfect beginning with 5.0, DrawPerfect
beginning with 1.0, ED beginning with 3.0, Shell beginning with 3.0, 
and LetterPerfect beginning with later releases of version 1.0, when 
WPCorp introduced macros for LetterPerfect), and it will probably work 
with any new products WPCorp develops using a similar macro language, 
as well as with versions of WP, DR, PL, ED, SH, and LP that do not yet 
exist.  It does not work with macros for the Windows version of 
WordPerfect. 

By creating a text representation of a macro, MacAscii allows you to
print macros.  More importantly, it allows you to edit macros using
your favorite editor rather than WPCorp's awkward macro editors, as
well as to use other kinds of powerful text processing programs in
working with WPCorp macros (one important example appears below).  Thus
you can edit macros too big to handle in the built-in macro editors of
WPerf, PlanPerfect, and DrawPerfect.  And if you have DrawPerfect or
LetterPerfect, and therefore Shell, you can edit Shell macros even if
you do not have ED.

In order to handle all these different macros, MacAscii requires the
appropriate MRS file -- WP.MRS, DR.MRS, PL.MRS, ED.MRS, LP.MRS, or 
SH.MRS (do NOT use KEYS.MRS).  Generally, if you have any reason to 
want to work with a WPCorp macro, you have the appropriate MRS file, 
because each of the programs comes with its own MRS file.  However, if 
you are a DrawPerfect user, you may want to work with Shell macros even 
though you may not have SH.MRS. MacAscii allows an alternative to MRS 
files -- MRQ files.  The shareware distribution of MacroAid comes with 
SH.MRQ, and registered users will receive other MRQ files. 

Problems can arise if you use the wrong MRS (or MRQ) file.  If you are
converting a macro to its text representation, MacAscii checks to see 
that the product and major version of the macro and the MRS file are 
the same, and if they are not (or if they are, but the minor version of 
the MRS file is earlier than the minor version of the macro) , it will 
not do the conversion.  (In "WordPerfect 5.1," the major version is 5 
and the minor version is 1.)  There is no checking when you convert 
from text to macro. 

WPCorp on occasion changes the MRS file with interim releases of a
version of a program.  This creates several problems.  First, even if
you have correctly matched the versions of the MRS file and the macro,
the macro could contain commands not in the MRS file, because the macro 
is based on a later interim release than the MRS file.  These commands 
will be flagged as unknown.  Second, both the MRS file and the macro 
could be based on a later interim release than your program.  If that 
happens, and you convert a text representation of a macro to a macro, 
the macro could contain commands unknown to your release of the 
program.  The best, and perhaps only, solution to these problems is to 
make sure that both your MRS file and your program are up to date. 

The text representation of macro commands differs among the languages 
for which versions of WPCorp programs exist.  However, the commands 
themselves are stored in a macro file in a way that does not depend on 
the choice of a language, and the MRS file controls how the text 
representation of what is stored in a file appears.  Thus if you have a 
macro, say, CALC.WPM, and you translate it to text format using 
MacAscii and the English language WP.MRS file, text output will use 
English language command and key names.  But if you use the French 
language WP.MRS file, text output will use French language command and 
key names.  Thus the same version of MacAscii can be used whatever 
language you use for command names and key names, so long as you have 
the appropriate MRS file.  In translating from text to macro, you must 
use the MRS file that matches the language used to represent command 
and key names in your text. 

MacAscii does not check the syntax of your macros, and it will
faithfully translate errors exactly as they appear. However, when
translating from ascii text files or WP5 documents, it sends a warning
to the screen when it finds a macro or key command inside a {;}
comment.  Commands inside comments are legal, but often they result
from a missing tilde at the end of a comment.

The syntax for using MacAscii can get complicated, because there are a
lot of options.  Typically, however, you need only this:

   >MacAscii -iIfile -oOutfile -mMRSfile

Here is a more complete statement of the syntax, with explanations of
the various command line items:

>MacAscii -iInfile -oOutfile (or -wOutfile) -mMrsFile [Options]

     -iInfile    Infile is the filename of the file to be converted. It
                 can be a macro, an ascii text file, or a WPerf 5.x
                 document file.

     -oOutfile   Outfile is the filename of the output file.  If Infile
                 is an ascii text file or a WPerf 5.x document, Outfile
                 is a macro.  If Infile is a macro, Outfile is its
                 ascii text representation.  If you want to convert a
                 macro to its text representation as a WPerf 5.0 file,
                 use the -w switch.

     -wOutfile   Outfile is the filename of the output file when you
                 are converting a macro to its text representation as a
                 WPerf 5.0 document.

     -mMRSFile   MRSfile is the name of the MRS file to govern the
                 conversion.  If no extension is provided, the
                 extension MRS is assumed.

     -aMRQfile   Use -a instead of -m if you are using an MRQ file
                 instead of an MRS file.


      Options:

     -cCfgfil    Because the MacAscii command line can grow long, you
                 have the option of including any of the command line
                 parameters (except -cCfgFil) in a configuration file.
                 (The configuration file is an ascii text file.  Each
                 line contains a single parameter which would otherwise
                 go on the command line, complete with its -switch.)
                 If you do not indicate otherwise on the command line,
                 MacAscii will look for the configuration file
                 MacAscii.Cfg in the directory where Macascii.Exe is
                 found (unless you are using a DOS version earlier than
                 3.0, in which case MacAscii looks in the current
                 default directory).  To use a different configuration
                 file, specify it with -c on the command line, where
                 Cfgfil is the full name of the configuration file you
                 want to use.

                      If, for example, you almost always use MacAscii
                      with WPerf macros, you might well want to specify
                      the MRS file in the configuration file, so you do
                      not have to put it on the command line each time
                      you use the program.  You would then have a 
                      configuration file with a single line of ascii 
                      text that might look like this:
                      
                      -mc:\wp51\wp.mrs
                       

                      Parameters specified on the command line override
                      parameters specified in the configuration file.
                      Thus if you have -mwp in the configuration file
                      and want to use MacAscii with a DR macro, you can
                      simply put -mdr on the command line, and that
                      will override the choice of -mwp in the
                      configuration file.



     -schar      A space that is part of a macro ("macrospace") is
                 represented in WPCorp's macro editors by a dot (which
                 happens to have the ascii value 250 decimal), rather
                 than by a blank space.  By default, MacAscii assumes
                 that this is how you want macrospaces to be
                 represented in text output and how they are
                 represented in text input.  But the WPCorp dot can be
                 a bad choice in some situations.  First, it is harder 
                 to type than a blank space.  Second, some E-mail
                 systems do not permit high ascii characters, and some
                 editors have problems with them.  The -s switch allows
                 you to use a different character to represent a
                 macrospace -- just provide the character after the -s
                 (e.g., -s# to use # for the macrospace).  If you want
                 to use a blank, you can just leave out the character
                 after the -s (and if you are converting from WP5 to
                 macro, you can leave out the -s entirely).  If you
                 want to use a character that you cannot put on the DOS
                 command line, represent it this way: \nnn, where nnn
                 is the number of the ascii character (in decimal)
                 (e.g., -s\124 for the vertical bar).

     -n          Represent low ascii characters as {\nn} in ascii text
                 file output.  Macros may contain low ascii characters
                 (characters with values below 32) for cursor
                 positioning and other purposes.  MacAscii has no
                 trouble with these characters, but you may have
                 trouble with ascii text file output that contains
                 these characters, because they include such things as
                 carriage return, line feed, form feed, end of file,
                 and others which may cause your printer to do strange
                 things.  The -n option represents these low ascii
                 characters as {\nn}, where nn is the decimal digits
                 representing the ascii characters (for example, form
                 feed becomes {\12}).  When you convert an ascii text
                 file containing these symbols back to a macro,
                 MacAscii will process them correctly whether or not
                 you use the -n switch.

     -d          Dump.  This option writes to standard output a
                 complete list of the macro and key commands supported
                 by the MRS or MRQ file specified on the command line
                 with it.  (Note that the list may include commands not
                 actually available to you; WPCorp apparently includes
                 in the MRS file commands not yet implemented in its
                 programs.)  If you use this option, the only other
                 parameter required on the command line is the -m or -a
                 switch identifying the MRS or MRQ file.


Notes on Macro Commands and Key Commands

In converting from text to macro, MacAscii assumes that anything
appearing between left and right braces ({}) is a macro command or a
key command.  It then tests that assumption by comparing the text
against the macro and key commands obtained from the MRS (or MRQ) file.
If it does not find an EXACT match (ignoring case), MacAscii concludes
the material between braces is not a command, outputs it to the macro
as simple text, and sends a warning message to standard output.  (To
make sure you have an exact match, run MacAscii with the -d option,
redirect the output to your printer, and consult the printed list as
you edit the text forms of macros.)

Because MacAscii is not case sensitive in matching commands, you cannot
use, say, {Assign} as simple text in a prompt message.  Use, for
example, <ASSIGN> instead.  (This substitution is not necessary in
comments.)

MacAscii does, however, recognize several {} symbols which are not
WPCorp macro or key commands.  First, there are special "comment"
symbols.   Anything that appears in an ascii text file or WP5 file
between these symbols is ignored in the conversion to macro format.
These symbols can therefore be used to "comment out" portions of the
macro code, or simply to include text in the text file that is not
included in the macro.  (Note: this kind of "comment" differs from the
WPCorp macro comment -- e.g., {;}This is a comment~ -- because the
WPCorp comment is included in the converted macro.)  These symbols come
in pairs.  Thus {(*} begins a comment and {*)} ends a comment (these
symbols will be familiar to Pascal programmers).  Similarly, {/*}
begins a comment and {*/} ends a comment (these symbols will be
familiar to C programmers).  Anything between the beginning and ending
symbols in a pair is ignored.  These symbols function as pairs, and the
two types cannot be mixed.  Thus if you begin a comment with {(*}, {*/}
will not end it -- the comment will not end until a {*)} is found.
This allows you to, for example, comment out a section of code with
{/*} and {*/} and then comment out a larger section, which includes the
first section, by using {(*} and {*)} at the beginning and end of the
larger section.

Second, in ascii text files only, symbols in the format {\nn} are
recognized as indicating low ascii characters corresponding to the
digits nn.  See the discussion of the -n option above for more detail.

Third, in ascii text files only, symbols in the format {\\m,p} are 
recognized as indicating the character in character set m and position 
p, as WPCorp defines these character sets.  This allows representation 
of any character WPCorp programs can use, whether or not they have 
ascii representations. 

Format of ASCII text files

(1)As output

   MacAscii starts ascii text file output with the word "File,"
   followed by the name of the input macro file.  The next line begins
   with the word "Description," followed by the macro description (if
   any).  The body of the macro begins with the following line
   (MacAscii also inserts some blank lines for readability).

   Tabs used for formatting the macro are converted to blank spaces
   (four spaces per tab).  Macrospaces are represented by the standard
   WPCorp dot (unless you select a different character).

   Exotic characters in the WPerf character set that have no ascii
   equivalent (such as Cyrillic characters and many mathematical 
   symbols) are represented by symbols in the format {\\m,p}, as 
   described above. 

   The ascii output file may contain ascii characters with numbers less
   than 32.  These characters are used for cursor positioning in
   macros, and they are sometimes used in macros to set "markers" in a
   document.  Although these "low ascii" characters do not cause any
   difficulty for MacAscii, they can cause other difficulties.  They
   may turn out to be printer control characters (for example, ascii 7
   causes a Panasonic KXP-1091 printer to beep, 18 turns on compressed
   mode, and 19 disables the printer from receiving data).  They may
   disappear if the ascii text is transmitted via E-mail.  To avoid
   these problems, you may use the -n option, described above.

(2) As Input

   MacAscii does not necessarily treat the beginning of the ascii text
   file as the beginning of the macro.  Leaving aside "boxed macros"
   (discussed below), MacAscii assumes the macro does not begin until
   it finds the first line which (a) is not entirely blank; (b) does
   not contain the string "File" (without the quotation marks); (c)
   does not contain the string "Description" (without the quotation
   marks); and (d) does not contain the string "{DESCRIPTION}" (case
   matters for the File and Description strings).  If a line does
   contain the string "Description" or the string "{DESCRIPTION}",
   MacAscii assumes what follows on that line is the macro description,
   and it inserts that description into the output macro.  If you need
   to, for example, include the word "Description" on the first line of
   your macro, put {;}~ (followed by a hard return) at the beginning of
   your file; that line will be treated as the beginning of the macro.

   The macro editors in WPCorp products display the macro enclosed in a
   box.  MacAscii will handle properly macros whose body (but not the
   File and Description lines) is enclosed in such a box.  Thus text
   macros in more or less the format displayed by the WPerf macro
   editor can be handled.

   Ascii text file lines end with a Carriage Return and Line Feed
   (CRLF).  Sometimes screen capture or downloading in certain ways
   from electronic services leads to files with lines that end with
   only one of these characters. MacAscii will not handle such files
   properly (however, MacAscii permits CRLF to be omitted at the end of
   the last line, and it permits the last line to end with Ctrl-Z).

   Line length is limited to 200 characters. 

   Either spaces or tabs may be used to represent blank space used for
   formatting the macro.  However, if you choose to use a blank space
   for the macrospace, confusion can arise between the macrospace and
   formatting blank space.  If you indicate with -s that the ascii text
   file uses a blank (ascii 32) for macrospace, MacAscii assumes that
   all blank spaces are macrospaces, except (a) blanks at the beginning
   of a line, (b) blanks at the end of a line, and (c) blanks preceding
   a comment.  These assumptions will usually be correct, but may
   occasionally be wrong.


Format of WP5 document files


(1) As output

   MacAscii includes File and Description lines at the beginning of WP5
   output, as described above for ascii text output.  Macro and Key
   commands are bolded.  Apart from that, the output file has no
   peculiarities.

(
9C2) As input

   WordPerfect codes not relevant to macros (that is, codes used only
   for formatting the WP5.x document) are ignored entirely.  The rest
   of this discussion assumes none exist, because their presence would
   have no effect.

   The required format is more restrictive than in the case of ascii
   text files.  Macascii assumes the text of the macro does not begin
   until the first line which (a) is not entirely blank, (b) does not
   begin with the string "File", (c) does not begin with the string
   "Description", and (d) does not begin with the string
   "{DESCRIPTION}".  Compare those assumptions with the assumptions for
   ascii text files, where "File", "Description", and "{DESCRIPTION}"
   may appear anywhere in the line.  "Boxed macros" are not handled
   properly -- avoid them in WP5 files.

   Blank space used for formatting must be represented by tabs.  Both
   the conventional dot space and other WPerf codes implying blank
   space (space, hard space, soft return, etc.) are treated as
   macrospaces.


Using Other Macro-To-Text Programs

Several other programs convert macros to text.  They may begin the text
with lines that are not part of the macro and that MacAscii is not
designed to ignore (for example, lines beginning "Desc:" or
"{VERSION}").  At least one such program also includes a final line
which is not part of the macro.  Files like these need editing before
MacAscii can convert them to macros.


MRQ Files

MRQ files are files we have made from MRS files.  They contain the
information MacAscii requires from an MRS file. Unfortunately, you
cannot update your MRQ file easily whenever WPCorp releases a new MRS
file.

Most people will have no need for MRQ files, although owners of
DrawPerfect who have not purchased Office may find SH.MRQ useful.
MacAscii may run slightly faster with MRQ files instead of MRS files,
but any difference would be vanishingly small and probably undetectable
without complex measuring equipment.


Writing Macros In Ascii Text File Format

Editing macros in ascii text file format allows you to use powerful
text-processing techniques to speed the writing of macros and to make
macros more readable.  Apart from search and replace capabilities of
various editors beyond those available in WPCorp products, these
techniques include use of capabilities made available through standard
"macro processors," where "macro" is used in a slightly different sense
here.  M4, a standard Unix utility program for which several DOS
versions exist is a good illustration.  Michael M. Rubenstein's free
DOS version of M4 is recommended.  Because DOS versions of M4 can be
hard to locate, with Mr. Rubenstein's permission a copy of his version
of M4 will be included with paid-for copies of MacroAid, although not
with the shareware distribution of MacroAid.  (You can find a good deal
more information about M4 in Software Tools in Pascal, by Brian W.
Kernighan and P.J. Plauger.)  Borland's Turbo C preprocessor program,
CPP, has some similar capabilities, but M4 is more powerful and
preferable in several other ways.

Two of M4's many capabilities are important here.  First, there is the
"include" capability.  Suppose we have two ascii text files, A.ASC and
B.ASC.  A.ASC looks like this:


   A Line 1
   include(b.asc)dnl
   A line 2

(Note: the "dnl" is there to prevent generation of extra blank lines)

and B.ASC looks like this

   B Line 1
   B Line 2

Then, when we process A.ASC through M4, the result looks like this:

   A Line 1
   B Line 1
   B Line 2
   A Line 2

You can use the "include" directive to incorporate frequently used
macro code in your ascii text files without actually having to copy it
each time.  Suppose, for example, you frequently need to turn Reveal
Codes off in a macro.  You might prepare an ascii text file, RCOFF.ASC,
that looks like this:

   {LABEL}rco~
       {IF}{STATE}&4~
            {IF}{STATE}&512~{Reveal Codes}{END IF}
       {END IF}
       {RETURN}


That is a little "subroutine" which can easily be included in a macro
you are writing.  We will use RCOFF.ASC below.

Another capability is "define," which is a little more complicated.
With this instruction

   define(dog,cat)dnl

M4 will substitute the string "cat" for "dog" each time "cat" appears.
Substitutions may actually be much more complicated, because defines
may use "arguments," $1 to $9.  Here is a silly example:

   define(dog, cat$1$2)dnl

Then M4 would replace

   dog(big, blue)

by

   catbigblue.

Now for some less silly examples.

"Defines" can be used to develop a library of standard routines for use
in macros.  For example, macros frequently ask the user for a yes or no
response, and then go to different parts of the code depending on what
the answer is.  Each instance uses basically the same programming
commands, but the prompt for the user differs each time, and the
various labels used also differ.  A define, where the arguments
represent the varying parts of the standard programming commands, may
simplify the writing.  The following is how we might do this:

   define(YesNoQuery, {LABEL}$4
                       {CHAR}ynq~$1~
                       {CASE}{VARIABLE}ynq~~
                            Y~$2~
                            y~$2~
                            N~$3~
                            n~$3~
                            ~
                       {GO}$4~
   )dnl

In this example, the message to the user and the necessary labels are
arguments supplied when YesNoQuery is used. A line like the following
will produce the right code structure in the macro:

   YesNoQuery(Continue? (Y/N):,DoYes, DoNo, DoYNQ)

and if there is another such structure in the same macro, another
single line invokes it, with a different message and different labels:

   YesNoQuery(Save the file? (Y/N): SaveIt, DoNotSave, AskSave)

YesNoQuery is used in a macro below.

For another example, it is sometimes convenient to determine whether
the character at the cursor is an upper case letter.  The following
define makes it easy to incorporate the necessary programming
instructions:

   define(IsUpper,{KTON}{SYSTEM}right~~>64&{KTON}{SYSTEM}right~~<92)dnl

That gives us a convenient way of placing that expression, not easy to
type, in the middle of the macro.

The last example is a convenient way of using the Reveal Codes
subroutine shown earlier:

   define(TurnRevealCodesOff, {CALL}rco~)dnl

All these defines can be placed in a file, LIBRARY.ASC, for regular
use.  It looks like this:

   define(YesNoQuery, {LABEL}$4
                       {CHAR}ynq~$1~
                       {CASE}{VARIABLE}ynq~~
                            Y~$2~
                            y~$2~
                            N~$3~
                            n~$3~
                            ~
                       {GO}$4~
   )dnl
   define(IsUpper,{KTON}{SYSTEM}right~~>64&{KTON}{SYSTEM}right~~<92)dnl
   define(TurnRevealCodesOff, {CALL}rco~)dnl

Of course, LIBRARY.ASC could have many more defines, and you could have
several such files.

Using these particular defines in a sensible short macro is not easy,
so here is a nonsense macro:

   include(library.asc)
   {DISPLAY OFF}
   TurnRevealCodesOff
   YesNoQuery(Is this a silly macro?,IsSilly,IsNotSilly,Q)
   {LABEL}IsSilly~
           a{Left}{IF}IsUpper~
           a is upper case{ELSE}
           a is lowercase{END IF}{QUIT}
   {LABEL}IsNotSilly~
           wrong answer!{QUIT}
   include(RCOFF.ASC)dnl

If this macro is in a file named SILLY.ASC, this DOS command causes M4
to process it:

   M4 Silly.Asc >Expand.Asc

The resulting Expand.Asc looks like this:


   {DISPLAY OFF}
   {CALL}rco~
   {LABEL}Q
                       {CHAR}ynq~Is this a silly ?~
                       {CASE}{VARIABLE}ynq~~
                            Y~IsSilly~
                            y~IsSilly~
                            N~IsNotSilly~
                            n~IsNotSilly~
                            ~
                       {GO}Q~

   {LABEL}IsSilly~
                       a{Left}
   {IF}{KTON}{SYSTEM}right~~>64&{KTON}{SYSTEM}right~~<92~
                       a is upper case{ELSE}
                       a is lowercase{END IF}{QUIT}
   {LABEL}IsNotSilly~
   wrong answer!{QUIT}
                       {LABEL}rco~
                            {IF}{STATE}&4~
                                 {IF}{STATE}&512~{Reveal Codes}{END IF}
                            {END IF}
                       {RETURN}

Of course, once LIBRARY.ASC has been developed and tested, there is no
need to look at files like EXPAND.ASC, which is just an intermediate
file used as input to MacAscii.  All you need to look at is SILLY.ASC,
which is shorter, easier to write, and easier to read than EXPAND.ASC.

Much of the power of using a macro processor like M4 comes from
developing a standard library of defines and includes.  If you write a
lot of macros, it is well worth the effort to develop that library.

One word of warning:  M4 does not handle high ascii characters. 


III.  MacCalls

Some macros will not work unless other macros are available -- they use
{CHAIN}, {NEST}, and {SHELL MACRO} commands.  Particularly if you have
acquired a new collection of macros from somewhere, it can be very
helpful to trace through the sequence of calls to other macros.
MacCalls traces the sequence for you.  Here is how it is used:

   >MacCalls MacFileSpec [ShellMacroDir]


     MacFileSpec:   file specification (with drive, path if needed) of
                    macros to search.  May include wildcards.
                    Extension defaults to WPM.

     ShellMacroDir: shell macro directory.  Use only if shell macros
                    are not in the MacFileSpec directory.

     Output goes to standard output, and may be piped or redirected.

     Only the first 65,518 bytes of macro body are searched; that is
     about the largest possible WPCorp macro.

MacCalls finds the first file matching MacFileSpec and searches it for
{CALL}, {NEST}, and {SHELL MACRO}.  It reports the name of the file it
is searching, and then, indented under it, lists the first macro
{CALL}ed (if, as is usually the case, the name of the macro called does
not have a path or extension, MacCalls supplies the path and extension
of MacFileSpec -- or, for {SHELL MACRO} commands, MacCalls supplies
ShellMacroDir as the directory if that has been specified on the
command line -- and otherwise it uses what it finds in the macro).
Then, if it can find this macro, it searches it for {CALL}, {NEST}, and
{SHELL MACRO}, and reports in the same way.  If it cannot find the
file, it simply reports that and moves on to the next file.  And so
forth.

The result is tree-like output, reporting the entire chain of macro
calls.  (Even if the files can be found, the entire chain is not always
reported.  To avoid voluminous output and the possibility of infinite
loops, no macro file is searched more than once.)  Here is an example,
generated by

   >MacCalls * >out

in a subdirectory with a few macros constructed for test purposes.  The
output is redirected to the file "out."  Out then contains the
following:

D:\WORK\FISH.WPM --

  Nests:
  D:\SMACS\STUFF.WPM not found or opened

D:\WORK\C2.WPM --

  Chains:
  D:\WORK\THE.WPM not found or opened

  Nests:
  D:\WORK\Q1.WPM not found or opened
  D:\WORK\Q2.WPM not found or opened
  D:\WORK\TEST.WPM --

    Chains:
    D:\WORK\C2.WPM already processed
    D:\WORK\FISH.WPM already processed

    Nests:
    D:\WORK\F1.WPM not found or opened
    D:\WORK\N2.WPM not found or opened

    Shell Macro calls:
    D:\WORK\S1.SHM not found or opened


D:\WORK\TEST.WPM already processed

You can make MacCalls pause at the end of each full screen by piping
the output to the DOS program MORE:

   >MacCalls * |MORE

or you can pipe it to Vern Buerg's LIST program, which will allow you
to page back and forth through the output:

   >MacCalls * |LIST /s


IV.  MacCrush

MacCrush shrinks macros by removing comments as well as tabs and
returns used only for formatting the macro.  It also changes all label
and variable names (except for variables 0 - 9 and shell variables) to
two letter symbols.  The result is an unreadable mess, but there is no
reason to read it -- keep the original source file, and if you ever
need to do any editing, edit the original and recrush.  (In fact, if
you wish to distribute macros without revealing how they work, try
crushing them.  MacCrush may make the logic of the macro so difficult
to follow that there is little risk of revealing anything important.)
The main point of doing all this is to make the macro load and execute
faster, although the speed improvement, if any, is not likely to be
large and in small macros will probably not be noticeable.  (Prior to
the 6/30/90 release of WordPerfect 5.1, comments, tabs, and returns in
a macro slowed down execution, but WordPerfect now eliminates those
characters when it loads the macro.  Therefore, there may be no
improvement in execution speed in recent versions of WordPerfect, but
there may still be a difference in loading time.)

Note that you may not want to change all the labels or variable names,
mainly because variables can be referenced by different macros -- that
is, macros can communicate with one another by storing information in
variables, since variables are, as WPCorp says, "global."  In fact,
that is the reason shell macro names in non-shell macros are not 
changed -- we assume that a shell variable referred to in a non-shell
macro is also referred to by at least one other macro, a shell macro.

There are more complicated reasons for not changing certain label or 
variable names.  Rather than reference a label directly, you may store 
the name in a variable and use the variable where the label name goes.  
MacCrush cannot tell, when you store a string in a variable, that it 
will later be used as a label, and it therefore cannot change the name 
appropriately.  Similarly, you can construct a label name by 
concatenating a variable and a string (for example, 
{VARIABLE}Prefix~Jump~ can be used to create a family of labels, such 
as 1JUMP, 2JUMP, etc.), but MacCrush will be confused by this mixture 
of variable and label.  For this reason, MacCrush allows you to supply 
a list of labels and variables whose names the program does not change.  
(In the example just given, even though JUMP by itself is not a label 
name, you would put JUMP in the keep list, along with Prefix, so as not 
to produce incorrect results.  You might want to put Prefix in both the 
variable and the label keep lists, since when {VARIABLE}prefix~jump~ is 
found where a label belongs, MacCrush may think Prefix is a label 
name.)  

Here is how you use the program:

   >MacCrush Infile Outfile [Keepfile] [-N] 

    Infile   a WPCorp macro. Extension defaults to WPM.

    Outfile  Output macro file. Extension defaults to Infile's
             extension.

    Keepfile Optional file with list of names not to crush.

             Keepfile is an ascii text file.  If there are variable
             names you do not want to have changed, the first line of
             Keepfile must begin with the word "Variables" (without the
             quotation marks) and include nothing else.  Each line
             after that consists of the name of a variable (case does
             not matter).  When you are finished with the variable
             names, if there are any label names, the next line should
             read "Labels".  After that come the labels not to change,
             one per line (again case does not matter).  If you want to
             keep some label names but no variable names, the first
             line in the file reads "Labels".

    -N       Option to prevent crushing of labels or variables.  -NL 
             indicates no crushing of labels, -NV indicates no crushing 
             of variables, and -NVL (or -NLV) indicates no crushing of 
             either one.     

MacCrush sends a report to standard output on the variable and label
names it has changed, indicating what it has changed them to.  This
report may occasionally be useful for debugging purposes, but usually
it serves no purpose.


V.  MacChang

WPCorp macros have a prefix containing, among other things, codes
indicating the WPCorp product and the version number.  MacChang allows
you to change that information.

MacChang is useful primarily if you want to translate a WPCorp macro 
written for one WPCorp program (say, WPerf) to another (say, PlanPerf).  
A useful way to begin is simply to change the product and version 
information stored in the macro, look at the text of the resulting 
macro, and see what else has to be changed (sometimes nothing else has 
to be changed). 

Here is the syntax for using MacChang:

   >MacChang Infile Target

     Infile  Filespec of WPCorp macro, including extension

     Target  WPCorp product type to change macro to.

             Target must be one of the following: WP50, WP51, DR10,
             DR11, PL50, PL51, ED30, SH30, LP10

MacChang alters the product type of the input file and renames the
input file by changing the extension to the extension appropriate to
Target.

Note that earlier versions of MacChang erroneously referred to LP11.

For example,

   >MacChang sign.wpm PL51

changes a WPerf macro (sign.wpm) to a PlanPerfect 5.1 macro (sign.plm).

(Note: you will want to run MacChang on a copy of your original macro.)


VI.  MacFind

MacFind searches for strings in macro files (and keyboard files).  The
strings may include programming and key commands.  The output reports 
the pathnames of the files in which the string was found and 
(optionally) whether the string was found in a macro description or in 
the body of a macro. 

Programs that search for text strings in files are very common.  Most
of them will not work for finding text strings in macros, because
strings are stored peculiarly in the body of a macro.  Also, these
programs will not find programming and key commands, because the string
representation of these commands (e.g., {ASSIGN}) has no resemblance at
all to what is actually stored in the macro.  MacFind does not suffer
from these limitations.

Here is the program syntax:

    >MacFind FindText MacFile [/mmrsfile] [/aaltfile] [/C] [/F] 

       FindText  String to find. If it has blanks, enclose in quotes.
                 If it has ", enclose in '.  If it has ',  enclose in
                 ". No more than 127 characters.

       MacFile   File spec (with drive, path, wildcards if needed) of
                 macros to search.  Extension defaults to WPM.

      /mMRSfile  needed if FindText has {} symbols.  Default extension
                 is mrs.

      /aAltfile  MRQ file, used instead of MRS file.

     /C          Case insensitive search.  If the FindText includes
                 programming or key commands, the search will be case
                 sensitive even if you use the /C switch.

     /F          Full output.  Use this switch if you want the output 
                 to distinguish between matches found in the body of a 
                 macro and matches found in the macro description. 

     Only the first 60,000 bytes of a macro are searched.  For macro
     files, both the description and the first 60,000 bytes of the
     macro body are searched.  For keyboard files, the first 60,000
     bytes of the file are searched.

     Output goes to standard output and may be piped or redirected.

You must specify an MRS (or MRQ) file if the FindText contains a {}
sequence, even if that sequence is not actually a programming command
or a key command.  Without the MRS (or MRQ) file, MacFind cannot
determine whether a string within braces is a programming command or a
key command.

Note that if you use a wildcard such as *.*, MacFind may search through
macros for several different WPCorp programs (if you keep them all in
the same subdirectory).  However, MacFind translates your FindText
based on an MRS file for a single WPCorp program.  This can produce
spurious results.  For example, what is actually stored in a WPerf
macro for {VAR 0} is identical to what is stored in a Shell macro for
{ALT 0}.  Thus if you are searching for a FindText that includes {VAR
0}, MacFind may report that it found the FindText in a Shell macro,
although what it found in Shell macro terms has {ALT 0} instead of {VAR
0}.


VII.  MacRef

MacRef produces a standard programmer's cross-reference listing of a
macro.  This consists of a line-numbered listing of the macro, followed
by a list of the macro commands and macro key commands (that is, the {}
codes), the variables, labels, shell variables (for shell macros, all
variables are shell variables, and there is no separate listing of
shell variables), and system variables, each accompanied by a list of
the line numbers on which it appears.  Words used simply as text appear
in the line-numbered listing, but not in the subsequent list.

There are some gaps in the resulting list.  For example, you may have
in your macro something like

   {ASSIGN}fish~test~

and elsewhere

   {GO}{VARIABLE}fish~~

as well as

   {LABEL}test~

The cross reference listing for the label "test" will not have a line
number for the assign statement, because MacRef has no way of knowing
when it reads the assign that "test" is actually a label.

If MacRef finds programming or key commands inside comments, it lists
the line numbers after listing the macro itself. Although the macro
language permits commands to be placed inside comment, commands inside
comments often result from missing tildes.

Here is the syntax for using the program:


   >MACREF /ifspec /cfspec /mfspec [options]


      /i    Input file, a WPCorp macro.  Default extension is WPM.

      /c    Configuration file.  See below.

      /m    MRS file (e.g., wp.mrs).  The default extension is MRS.

      /a    Alternative to MRS file.  See the discussion under
            MacAscii.

      /s    Spacechar - the character used in ascii to represent macro
            space.  Defaults to WPCorp dot. To use, e.g. ,!, /s!.  Or
            use /s\nnn, where nnn is decimal ascii code.

      /n    Low ascii characters in output represented by {\nn}.

      Output goes to standard output and may be piped or redirected as
      needed.


The -s and -n switches are identical to those used with MacAscii and
are more completely described above under that heading.  They are
useful if you want to print the output or transmit it via E-mail, a
well as in some other situations. MacRef, however, does not require
these switches.  Exotic ascii characters in the ascii output use the 
{\\m,p} notation described above.                 

You can use a configuration file to avoid lengthy command lines.  A
configuration file is an ascii text file, with one parameter on each
line of the file.  (The parameters are exactly what you would otherwise
put on the DOS command line.)  Unless you specify a different
configuration file on the command line, MacRef will look for a file
named MacRef.Cfg in the directory were MacRef.Exe is located (or, if
you are using DOS 2.x, in the current default directory), and it will
use that file if it finds it.  A configuration file is a convenient
place to put -s and -n switches.  If you always use MacRef with one
type of macro (say, WordPerfect 5.1 macros), the configuration file is
also a convenient place to put the /m information.

For an example, we saved as f.wpm the alt-f macro from the 5.1
macros.wpk keyboard.  Here is the output (possibly distorted, depending
on what font you use to print it) from running the following command:

   >MacRef -if -m\51\wp

File                   f.WPM
Description            Find the Bookmark (see Alt-m).


     1: {IF}!{STATE}&4~
     2:     {RETURN}
     3: {END IF}
     4: {DISPLAY OFF}
     5: {LABEL}top~
     6: {ON NOT FOUND}{GO}up~~
     7: {Home}{Search}<<<MARK>>>{Esc}
     8: {CALL}del~
     9: {RETURN}
    10:
    11: {LABEL}up~
    12: {ON NOT FOUND}{GO}fail~~
    13: {Home}{Search Left}<<<MARK>>>{Esc}
    14: {CALL}del~
    15: {RETURN}
    16:
    17: {LABEL}del~
    18: {Backspace}{Backspace}{Backspace}{Backspace}{Backspace}{Backspace}
        {Backspace}{Backspace}{Backspace}{ Backspace}{Del}
    19: {RETURN}
    20:
    21: {LABEL}fail~
    22: {IF}{STATE}&8~
    23:     {CALL}main~        {;}Insubstructure~
    24:     {GO}top~
    25: {END IF}
    26: {PROMPT}ERROR:Can'tfindBookmark~
    27: {WAIT}20~
    28: {QUIT}
    29:
    30: {LABEL}main~
    31: {IF}{STATE}&4~
    32:     {IF}{STATE}&8~
    33:     {ELSE}
    34:         {RETURN}        {;}Mainscreen~
    35:     {END IF}
    36: {END IF}
    37: {Exit}
    38: {GO}main~


Macro Commands and Keys

{;}                      23    34
{BACKSPACE}              18
{CALL}                    8    14    23
{DEL}                    18
{DISPLAY OFF}             4
{ELSE}                   33
{END IF}                  3    25    35    36
{ESC}                     7    13
{EXIT}                   37
{GO}                      6    12    24    38
{HOME}                    7    13
{IF}                      1    22    31    32
{LABEL}                   5    11    17    21    30
{ON NOT FOUND}            6    12
{PROMPT}                 26
{QUIT}                   28
{RETURN}                  2     9    15    19    34
{SEARCH}                  7
{SEARCH LEFT}            13
{STATE}                   1    22    31    32
{WAIT}                   27

Labels

DEL                       8    14    17
FAIL                     12    21
MAIN                     23    30    38
TOP                       5    24
UP                        6    1



VIII.  MacShell

MacShell helps you run the other programs in MacroAid.  With MacShell,
you need not construct DOS command lines for the other programs,
because MacShell does it for you.  It presents you with a menu from
which you can select the program you want to run (either by moving the
cursor to the desired choice and pressing <Enter>, or by pressing the
highlighted letter for that menu choice).  For each program, you are
presented with an entry screen, where you fill in the necessary
choices.  If you then choose to execute the program, MacShell swaps
itself to EMS (if you have EMS available) or to disk (creating the file
MacShell.Swp in the current default directory, which must not be on a
floppy disk) so that ample memory will be available, executes the
program, and returns you to the MacShell menu.  Three other menu
choices are available (plus Quit); they are discussed below.

MacShell requires no command line parameters.  However, if you do not
like the colors it uses, you can put /m on the command line; MacShell
will then use color choices designed for a monochrome display.

To install MacShell, copy MacShell.Exe to your hard disk.  Copy
MacArgs.Exe, MacAscii.Exe, MacCalls.Exe, MacCrush.Exe, MacChang.Exe,
MacFind.Exe, MacRef.Exe, and MacroAid.Doc to (a) any directory on your
path; (b) the directory that will be the current default directory when
you use MacShell; or (c), if you are using DOS 3.0 or later, whichever
directory contains MacShell.Exe.

Note that loading MacShell requires about 167K of available memory, and
the various options require varying amounts of additional memory.  If
an option seems not to work, that may be because not enough memory is
available. However, if you have enough memory available to run MacShell
up to the point where it executes another program, you should have
enough memory available for MacShell to execute the other programs,
because of the swapping feature.

Using The Entry Screens

Each entry screen has a number of "fields" for you to fill in.  You can
move from field to field with the <Tab> key or the cursor arrow keys.
Usually, the <Enter> key will accept what is entered in a field and
move you to the next field.  In some cases, you enter a string, in
others you select among a limited set of choices, and in still others
you enter a single character. Often, you will be presented with a
default choice.

When you are satisfied with the contents of the fields on a screen, you
can simply accept all the choices by hitting <F7>, which will return
you to the main menu, or you can execute the program you have selected
by hitting <F9>.  If you used <F7>, your choices will be preserved (for
the current MacShell) session, or you can make them your permanent
defaults by cloning MacShell, as described below.

Hitting <F1> at any entry screen allows you to read the file
MacroAid.Doc.  Hitting <F1> works exactly the same as choosing Read
Docs from the main menu.

   Entering Strings:

If a string-entry field presents you with a default string, the default
will disappear if the first key you hit in the field is a character.
If you want to edit the default string, begin with a cursor-movement
key, such as a cursor arrow key.

In some cases, you are permitted to enter strings longer than the
displayed field (for example, filenames that include long paths will
not fit the displayed field).  Longer strings will cause the field to
scroll.

If while you are editing a string you change your mind and want to
restore the default choice, hit <ESC> or <CtrlR>.

Editing strings involves straightforward use of the usual editing keys.
Thus <Left>, <Right>, <Home>, <End>, <Del>, <Ins>, <Bksp>, <CtrlEnd>,
and <CtrlHome> work in the expected fashion.  To clear the entire
field, use <CtrlY>.  To delete the word to the right of the cursor, use
<CtrlT>.

In any field calling for a filename, you can select the filename from a
directory list.  To do so, hit <F5>.  Enter a path specification
including one or more wildcards (?,*) and hit <Enter>.  A directory
list will appear.  Move the cursor to the filename you want and hit
<Enter>.  (Subdirectories are included in the directory list.  If you
select a subdirectory, you will be presented with the file list for
that subdirectory.)

   Selecting From A Choice Set:

Several fields allow only a limited number of choices.  For example,
certain fields allow you only to choose between MRS and MRQ.  You can
change the displayed choice by hitting <Space>, <+>, or <->.

   Entering Characters:

Some fields require a yes/no choice.  Enter either Y or N.  There are
also fields for selecting Spacechar, where you enter almost any single
character.  Certain characters (such as ascii 10) cannot be entered
because they are interpreted as editing commands, and you should not
use >, <, or | as the Spacechar.  For characters that do not correspond
to single keys, use Alt and the number pad to enter the ascii number
for the character.

Cloning MacShell

One of the main menu choices allows you to "clone" MacShell, which
means to change the MacShell.Exe file.  When you clone MacShell, the
current contents of each of MacShell's entry screen fields becomes
MacShell's permanent default choice for that field (until you next
clone MacShell).  This allows you to configure MacShell for easier
operation.

You may find it helpful, for example, to set defaults for input and
output filename fields that indicate the appropriate directories (end
directory names with \), so that you only have to add filenames when
you use the program.  And if you always use the same MRS file with the
MacroAid programs, you might wish to make that MRS file the default MRS
file.

Reading The Documentation (Help)

Although MacShell does not provide context-sensitive help, it does
permit you to consult the file MacroAid.Doc at any entry screen (hit
<F1>) or by choosing Read Docs at the main entry screen.  (Normally,
MacroAid.Doc is the ascii text file version of this documentation that
comes with MacroAid, but you can use that name for any file you want.)
The Read Docs, or Help, feature of MacShell actually reads MacroAid.Doc
into a fully-featured file browser.  The most important command is
<ESC>, whic
9h you use to exit from the file browser.  Other commands are
described below.

   Moving around the file:

To move around the displayed file, you can use standard keys in
conventional ways (although WordStar-style alternatives also work).
Thus <Left>, <Right>, <Up>, <Down>, <Home>, and <End> work in expected
ways. <PgUp> and <PgDown> move a full window in the expected direction.
<CtrlPgUp> and <CtrlPgDown> move to the beginning and end of the file.
To move to a particular line, use <CtrlJ> followed by <L> (or <CtrlL>);
you will be prompted for a line number.

You can set up to four "bookmarks" in the file (they disappear when you
exit from the file browser).  <CtrlK> followed by a digit from 0 to 3
sets the appropriately-numbered bookmark.  You can then jump to a
bookmark you have set by hitting <CtrlQ> followed by the appropriate
digit.

   Searching:

To find particular strings in the file (such as the string "MacAscii"
when you want to help in using MacAscii), hit <CtrlQ><F>.  You will be
prompted for a search string.  Enter the string and hit <Enter>.  You
will then be prompted for options.  If you choose no options, the
search by default will be case sensitive and will go from the current
location in the file towards the end of the file.  You can change this
behavior by entering one or more letters as options.  For a case
insensitive search, enter a "u."  To search backwards through the file,
enter "b."  To search forwards towards the end of the file and then
continue from the beginning of the file towards the starting location,
enter "g."

Once you have found the first instance of a search string, you can
search again for the same string (with the same options) by hitting
<CtrlL>.

   Miscellaneous Commands:

If you wish to read a file other than MacroAid.Doc, hit <F5>.  You will
be prompted for a new filename in the usual fashion.

If for some reason you want to read a hex dump of the file you are
browsing, hit <CtrlH>.  This command is a toggle --hit it again to go
back to ascii.

By default, the file browser expands tabs.  If for some reason you
would rather see the actual tab characters in an ascii file (there are
none in MacroAid.Doc), hit <CtrlQ> followed by <T>.  This command is a
toggle.

Going To Dos

The Go To Dos option on the main menu loads a secondary command
processor and allows you to do whatever you want to at the DOS command
line (although you should not load a TSR or, if swapping is to disk,
run programs such as CHKDSK or disk defragmenters).  Type EXIT to
return to MacShell.  Because MacAscii swaps itself to EMS (or disk),
you should have enough memory available for most operations (and
MacShell tells you how much memory is available).  Depending on your
configuration, you may well have enough memory available to run, say,
WordPerfect. This would allow you to test whether the output from
MacAscii is a correctly working macro, and to make adjustments in the
input text file if it is not.

-----------------------------------------------------------------------

                          FOR MORE INFORMATION

If you need more information or have any questions or suggestions, you
can write to me at the address given at the beginning of this
documentation.  Electronic messages may be faster, however.  You can
leave EMail on CompuServe [70441,2414] (you can also leave messages in 
the WPGSA forum) or on GEnie [D.SEIDMAN] (you can also leave messages 
in the WordPerfect RT -- there is a Topic for Software by Seidman in 
the RT.  In addition, I monitor several networked WordPerfect BBS 
conferences more or less regularly, and you can leave questions or 
suggestions for me in any of them.  You are likely to get a faster 
response if you leave the message on the BBS I call than if you count 
on the network to get your message to me and mine to you.  Things 
change rapidly in the BBS world.  Generally the networks where you 
can find me are Smartnet, Relay (RIME), Metrolink, what used to be, 
and may still be, called Interlink, and FidoNet.  BBSs I call regularly 
and which carry one or more of these networks are listed below: 

D.C. Information Exchange, 202-433-6639
Arlington Software Exchange, 703-532-7143
Free Spirit, 301-283-0917
DataBit, 703-719-9648 (inactive at this writing -- it is my link to 
Interlink)


-----------------------------------------------------------------------



                          LICENSE INFORMATION


MacroAid is not in the public domain.  Both the collection and the
individual programs are fully protected by copyright. (M4 is not part
of MacroAid.)

You are granted without charge a license which permits (a) use of the
programs for a period of 30 days for evaluation and testing; (b) making
copies for distribution to others without charge, provided the programs
and the accompanying documentation are distributed together and without
modification; (c) posting the programs, together with the accompanying
documentation, on electronic bulletin board systems.

Use after the 30 day evaluation and testing period requires payment of
a license fee.  For a single copy (plus necessary archival copies), to
be used on only one computer at a time, the fee is $25.00.  For your
convenience, an invoice form is included below (in ascii-formatted
documentation file only).  For large quantities, discounts and site
licenses are available.  Write for information.  Any license for which
payment is properly made is valid for this version of MacroAid and any
subsequent versions.

What do you get for your license fee?  You get permission to use the
programs and the warm feeling that you are not violating the copyright
laws.  When we receive your license fee, we send additional MRQ files,
a copy of the latest version of MacroAid, and documentation in
WordPerfect format.  With the permission of the copyright holder, we
will send you a copy of M4.  We will send you notice of any significant
updates, and we will send you the updates for a small shipping and
handling fee.  And if you let us know about any problems you have with
the programs, we will try to solve them.

Users groups and other not-for-profit organizations may distribute
unmodified copies of MacroAid (not including any of the files provided
only to licensed users), together with its accompanying documentation,
for a fee to cover duplication and related costs, but not to exceed
$6.00.  Your payment of such a fee does not eliminate the requirements
concerning payment of a license fee.

The United States Department of Justice is granted a license, without
payment of fee, for all official use of MacroAid.


                          WARRANTY INFORMATION


These programs are distributed without warranties of any kind, express
or implied, including, but not limited to, the implied warranties of
merchantability and fitness for a particular purpose.

No representation or other affirmation of fact, including but not
limited to statements regarding suitability for use, or performance of
the programs, shall be or be deemed a warranty by the licensor for any
purpose, nor give rise to any liability or obligation of the licensor
whatever.


                                INVOICE


David Seidman
Software by Seidman
2737 Devonshire Place, N. W.
Washington, D. C. 20008

                                              DATE:

SOLD TO:

__________________________
__________________________
__________________________


Ŀ
 Description                               Price              
                                                              
Ĵ
                                                              
 License for MACROAID                       $   25.00         
                                                              
 additional licenses @ $25.00                _____.__         
                                                              
                                                              
                                                              
                                                              


                                Total:       $_____.__
 D.C. Residents add 6% D.C. Sales Tax:          ___.__

                         Total Charge:       $_____.__


Make checks payable to Software by Seidman.  Please mark checks 
"MACRO