Black Box 4/BlackBox.cdr/editors/qmac215.arj/QMAC.DOC

Text File | 1991-09-04 | 30KB | 814 lines

                 QMac  --  QEdit(R) Macro Program

       A translator utility to convert QEdit binary macro
        files to and from a more easily used text format.

                         Revision: 2.15
                       Date:  August, 1991


         QEdit(R) and QMac are Copyright (C) 1985-1991 by
       Applied Systems Technologies, Inc. (dba SemWare(R))
                       All Rights Reserved

          QEdit and SemWare are registered trademarks of
                Applied Systems Technologies, Inc.


DESCRIPTION
-----------
QMac is a translator of QEdit macro files.  It translates QEdit
macros from the binary file in which QEdit saves macros to a
text file which allows easy macro editing, and translates such
text files back into a QEdit binary file.

This allows you to "record" a macro using QEdit; fine-tune it by
editing the text representation of the macro; and then translate
the edited version and reload it into QEdit for replay.

QMac allows appending to or overwriting existing files, making it
easy to add new macros to existing files. QMac's text file format
allows comments, permitting documentation of the macros within
their "source file".


TABLE OF CONTENTS
-----------------
Description ................................................   1
Table Of Contents ..........................................   1
What's New? ................................................   2
License ....................................................   2
Quick Start ................................................   2
Running QMac ...............................................   4
Text File Format on Input ..................................   6
Text File Format on Output .................................   9
Error Messages .............................................  11
Acknowledgements & Contacts.................................  15
Revision History ...........................................  15



QMac 2.15 Documentation                                   Page 2


WHAT'S NEW?
-----------
     o  You now must include a pound sign "#" in front of an
        ASCII code.  This is to allow for future extensions of
        the macro language.

     o  Jump, JTrue and JFalse are now supported in QMac macros.
        There may be up to 32 labels in each macro, each of which
        can be the target of one or more jump instructions.  Only
        the first 32 characters of a label are significant.

     o  Now handles the shortcut method of repeating a QEdit
        command. ( See REVISION HISTORY )

     o  All new commands in QEdit Advanced 2.15, QEdit TSR 1.15,
        and QEdit for OS/2 1.55 are now supported.


LICENSE
-------
QMAC is FREE to licensed users of QEdit.

You may copy QMAC for purposes of evaluating it, and distribute
QMAC to others for purposes of evaluating it for their use.  If
you continue to use QMAC after evaluating it, you must register
your copy of QEdit.  See your QEdit documentation for
registration information.

If you distribute QMAC to others, you must distribute it AS-IS,
with no files altered, added, or removed from the package.  You
may not distribute QMAC in connection with any other product or
service, or for any consideration or 'disk fee'.

Operators of electronic bulletin board systems (Sysops) are
encouraged to post QMAC for downloading by their users, as long
as the above conditions are met.




QUICK START
-----------
Here is quick run-through of what you can do with QMac, including
recording a macro, saving it to disk, and converting it with
QMac.  The keystrokes mentioned below assume you are using the
default QCONFIG.DAT supplied with QEdit; if you have re-installed
your keyboard using QCONFIG, please modify as needed.



QMac 2.15 Documentation                                   Page 3


Recording the macro:

     (1) From inside QEdit, select MacroRecord.  (Either hit
     <Ctrl M> or select "Macro record" from the "Macro" menu in
     the pull-down menu system, by pressing <Escape><M><M>).

     (2) At the prompt that says "Assign to what key:" press a
     key to redefine.  We will use <Ctrl F10> (hold down the Ctrl
     key and press the F10 key).

     (3) Press Find <Ctrl QF>, type "the" and press Return,
     and type "IW" and press Return again.  (This is just an
     example of what you can do, you could of course record
     any legal series of QEdit keystrokes here.)

     (4) Select MacroRecord again to end the macro, as in
     step (1) above.

     (5) Now, you can press <Ctrl F10> to search for the word
     "the" in your text in just one step.

Saving the macro to disk:

     (6) Let's write this macro to disk in a file that QMac
     can use.  Select MacroWrite from the pull down menus, by
     pressing <Escape> then <M><W>.

     (7) Give it a filename of "FIND.MAC", and press Return to
     save this macro on disk.

Converting the macro to text:

     (8) Press Dos <Alt F9> to send a command to MS-DOS.
     Type:

          QMAC FIND.MAC FIND.TXT /A- /T

     to convert FIND.MAC to a text form in the file FIND.TXT.
     Press Return.  (The /T selects text output).

     (9) Press EditFile <Alt E> to load this file into QEdit.
     Type "FIND.TXT" to load the text file you just created
     with QMac.  Press Return.  You should see something like
     this on the screen:

          *
          * Converted by QMAC from: C:\FIND.MAC
          *
          ^f10    MacroBegin Find "the" Return "IW" Return


QMac 2.15 Documentation                                   Page 4


     Which is, of course, a text representation of the keystrokes
     you just recorded.

     (10) You can now edit your macro if need be.  Let's change
     the word "the" to "and", and save the file back to disk by
     pressing File <Ctrl KX>.

Converting the macro from text back to binary:

     (11) Press Dos <Alt F9> to send a another command to MS-
     DOS.  This time, type:

          QMAC FIND.MAC FIND.TXT /A- /B

     to convert FIND.TXT back to its BINARY form, FIND.MAC.
     (NOTE that we use /B to tell QMac to make the binary file
     from the text file we just edited).  Press Return.

Reloading the edited macro into QEdit:

     (12) We can reload the modified macro file into QEdit so
     we can use it.  Select MacroRead from the pull down
     menus, by pressing <Escape> then <M><R>.

     (13) Specify the same filename as before, "FIND.MAC"
     to reload the same macro file we've been using.  Press
     Return.

     (14) Now when you press Ctrl-F10, QEdit will search for
     the word "and" instead of "the".

As you can see, you can use QMac to convert macro files in
both directions:  from a human-readable text form to the
binary form that QEdit uses, and vice versa.


RUNNING QMAC
------------
To run QMac, at the DOS prompt type:

          QMAC ?

and press Enter.  You will see a summary of QMAC's operation
that looks similar to the following:



QMac 2.15 Documentation                                   Page 5


----------------------------------------------------------------
QMAC:  QEdit Macro Program II  v2.15  August 1991
Copyright 1989-1991, SemWare.  All Rights Reserved.  QMAC ? for help.

QMAC macfile txtfile [ /B | /T ] /A   /C /U /M /Q  /Ixx /Wyy /Ezz

macfile QEdit binary macro file to process
txtfile File containing text version of macros
/B      Binary output:  Create macfile from textfile
/T      Text output:    Create textfile from macfile
/A      Append mode:    Append output to existing output file

/C+     Continue macros with "&";  /C-: Don't use "&" (default)
/U+     Underscores in names;      /U-: Don't use underscores (default)
/M+     Mixed case names in text output (default);  /M-: Use all lower case
/Q+     Quote strings with double quote (default);  /Q-: Use single quotes
/Ixx    Indent output text to column xx.        (Default=9)
/Wyy    Wrap output text at column yy.          (Default=80)
/Ezz    Errors to tolerate before quitting.     (Default=20)
----------------------------------------------------------------

All of the command line switches are optional, and are only
necessary to control QMac's operation in special ways.  Do not
type the [] characters.

The "macfile" parameter is the name (including directory, if
needed) of a QEdit binary macro file, such as created by using
MacroWrite from inside QEdit.

The "txtfile" parameter is the name of a text file that contains
a human-readable representation of the same macros.

QMac will create whichever of the two files that did not exist
already:  If the text macros already exist, it will convert them
to binary.  Or if the binary macros already exist, it will
convert them to text.

However, if both files exist, you must supply one of the optional
switches to determine the direction.  The switch /B tells QMac to
create a Binary file, while /T tells it to create a text file.

If the output file already exists, you must also supply a /A+ or
/A- switch to tell QMac whether to "append" to the existing file.
With /A+ it will append, /A- tells QMac to overwrite the existing
file.

All of the other parameters besides /B, /T and /A, are completely
optional, and all but /E only affect QMac's operation when it is
converting from binary to text format.  See later sections for
advice on using the other command line switches.



QMac 2.15 Documentation                                   Page 6



QMac will prompt for any required parameters which are not
supplied at the DOS prompt.  This includes the file names, so you
can just type:

          QMAC

by itself, and let the program prompt you for information, if you
would rather not learn the various parameters.  Hitting RETURN
all by itself at any QMac prompt will halt QMac.

QMac 2.x will also accept the "old style" command line syntax
used in previous versions of QMac:

          QMAC macfile textfile om am

Where:
            om  == output mode.  Either: T(ext) or B(inary)
            am  == append mode.  Either: Y(es) or N(o)

This syntax corresponds exactly to the order in which QMac will
prompt you for information if you don't supply it.

The advantage to using the new command line switches over the old
syntax is that the command line switches may be entered in any
order on the command line.  If a switch appears more than once,
or if conflicting switches are specified, the rightmost switch
takes precendence.

You can mix the old syntax with the new.  For instance, if you
enter just  QMAC /A- at the command line, QMAC will prompt for
input, but will not ask about the append mode.


TEXT FILE FORMAT ON INPUT
-------------------------
The text format which QMac uses for macros is similar to that
used within your QCONFIG.DAT file for QEdit:

     key       [ MacroBegin ]  [ Command... ]  [ & ]
               [ "string" ]  [ xxx ]   [ * comment ]
               ....

The "key" name must start in column 1 of a line, and must be a
single key (no two-keys allowed).  It can either be the name of a
key that QEdit understands (such as ^pgup for <Ctrl PgUp>); or
the numeric scan code for a key.


QMac 2.15 Documentation                                   Page 7


By using the numeric scan code, you can assign macros to special
keys that do not exist on your keyboard, but which are generated
by a keyboard enhancer program.  You can also accomodate non-
standard keyboards on some clone PC's that have unusual keys.

A macro can optionally begin with the command "MacroBegin", but
this is not required in this version of QMac.

Following that, the macro can contain any number of commands
which QEdit understands.  See your QEdit manual for details, but
these are commands like "CursorRight", "EditFile", etc.

For instance a macro to make the cursor jump to the very first
character of the current file would be:

          @f2     MacroBegin BegFile BegLine

If a macro contains only the command "UnknownCommand", then that
key will have no action at all when in QEdit.  (You might use this
to "disable" certain keys in QEdit at certain times.  In order to
re-enable the keys, you would have to load another macro file
with those keys defined, or re-start QEdit).

Mixed interchangeably with commands, macros can contain quoted
strings of text.  These will be "typed" when you execute the
macro, just as if you had typed them.  Quoted strings can be
surrounded by either single or double quote characters.

If you need to embed a quote mark in a string, either use the
other quote mark to surround the string, or double up the quote
mark in the string:

          'This is a double quote: " within a string'
             or
          "This is a double quote: "" within a string"

would enter the following string in the macro:

          This is a double quote: " within a string

Quoted strings can be used to enter text in the file you are
editing, or to answer prompts or menus presented by QEdit.



QMac 2.15 Documentation                                   Page 8


For other ASCII characters that are difficult to enter, you can
include the decimal code directly in the macro.  For instance, to
include a literal form feed code in a macro, you could enter:

          "This is a form feed: " #12

and the 12 would be translated to an ASCII 12, or form feed, in
the macro.  Do not put quotes around an ASCII code entered this
way.  You can enter any ASCII code from 0 to 255 this way.  Be
sure to include the pound sign.

Anywhere an asterisk ("*") appears on a line, outside of a
quoted string, the rest of the line is treated as a "comment"
and is ignored by QMac.  You can use this to include notes to
yourself about how your macros work, or what they are supposed
to do.  Comments are not included in the binary macro file
that QEdit loads, so there is no penalty for including them in
your text macro files.

A macro can continue onto more than one line, simply indent the
second and subsequent lines of the macro one or more spaces.  The
macro continues until QMac runs out of text or encounters another
key at the beginning of a subsequent line.

If you include an ampersand ("&") as the very last character on a
line, the next line will be included in the macro, even if it is
not indented.

If you omit ampersands from your multi-line macros, you can more
easily reformat them using QEdit.  Simply leave a blank line
below each macro, and use the WrapPara <Alt B> command in QEdit
to re-wrap macros to make them readable.  Remember, though, only
the key name should appear in column 1, all other lines should be
indented one or more spaces.  Please note that quoted strings
containing spaces, or comments, may be wrapped incorrectly by
WrapPara, so be careful.

QMac ignores any blank lines or lines that start with a comment
("*") mark, so you can freely intermix those within or between
your macros as needed.

Lines in your text macro files can be up to 512 characters long.

A text macro file may contain an arbitrary number of key
definitions.  QMac does not check the number or size of macros
when creating binary macro files, because the limits on size and
number may change from version to version of QEdit.  However, it
does make a rudimentary check on total size to be sure that the
current versions of QEdit will be able to load the macro file.



QMac 2.15 Documentation                                   Page 9


You may include any number of blank or tab characters between
commands in a macro, and capitalization is not important on
input.  Also, QMac ignores the underscore ("_") character when
used inside command names.  So, any of the following are
equivalent:

     ^f2       macro_begin beg_line beg_file un_mark_block

     ^f2       MaCrO_BeGiN BeG_LiNe BeG_FiLe Un_MaRk_Block

     ^f2       MACROBEGIN    BEGLINE   BEGFILE   UNMARKBLOCK

You can use whichever form pleases you.  Note, however, that "_"
may not be used inside key names, only inside command names.
Underscores can be used inside label names for use with the jump
commands, and they will be considered a significant part of the
name.  So the following labels:

     My_First_Label:
     MyFirstLabel:

are different labels.  Labels are not case sensitive.

Place a label before the command to which you wish to jump.  A
label is distinguished by a trailing colon ":" which is
mandatory.


TEXT FILE FORMAT ON OUTPUT
--------------------------
When creating a text file from a binary macro file, QMac writes
macros in the same format as described above.

Literal ASCII characters whose decimal codes are between 0 and 31
inclusive (the "control codes") are written to the text macro in
decimal form, preceeded by "#".  All other quoted characters are
written as-is.

When interpreting macros containing jump commands, the original
names of the labels for the jumps are no longer available.  So
QMac will manufacture labels of the form "Labelxxx" where xxx is
a sequential number starting at zero.

So, for instance, if you compiled the following macro to binary
form with QMac:

     * Delete from the current line to the end of the file
     ^f10    MacroBegin REPEATIT: DelLine JTrue REPEATIT



QMac 2.15 Documentation                                   Page 10


And then converted it back to text, it would look something like
this:

     ^f10    MacroBegin Label0: DelLine JTrue Label0:

QMac will generate a separate numbered label for every Jump,
JTrue or JFalse command in the macro, even if the labels all
exist in the same place.

QMac gives you several command-line switches to control the
details of how it formats the text macros.  You can control the
capitalization, use of underscores, indenting, word wrapping, and
use of ampersands.

None of these controls have any effect on QMac when it is reading
text macro file(s), only when it is writing them.

The /C switch controls the use of the "continuation" character,
ampersand ("&").  By default, QMac does not write this character
on the end of lines which are continued (since automatically
continues macros on to lines that are indented).  However, if you
prefer this syntax, you can specify /C+ on the command line to
turn this on.  You may need to do this if you are sending text
macro files to someone using an older version of QMac.

The /Q switch tells QMac what your preferred quote mark is for
use around quoted strings.  The default is /Q+, which means use a
double quote mark (""").  By specifying /Q-, you can force QMac
to use single quote marks ("'") around quoted strings.

The /M switch tells QMac whether you wish to use "mixed case" in
command names.  The default is /M+, which makes the QEdit command
names appear as they do in the QEdit manual (example:
ToggleEGA43).  Specify /M- to write all lower-case names.  Key
names are always written in all lower case.

The /U switch tells QMac whether to include underscores ("_") in
command names.  The default is /U-, which means no underscores
are written.  When /U+ is specified, QMac will insert an
underscore before each capitalized letter in a command (as they
are capitalized in the QEdit manual).

Here is a summary of how commands will look with the different
combinations of /M and /U:

     /M+  /U-  (default)    MacroBegin  BegLine  ToggleEGA43
     /M+  /U+               Macro_Begin Beg_Line Toggle_EGA_43
     /M-  /U-               macrobegin  begline  toggleega43
     /M-  /U+               macro_begin beg_line toggle_ega_43



QMac 2.15 Documentation                                   Page 11


Note that the third option (/M-, /U-) is the way the previous
versions of QMac always wrote commands.

Again, it matters not which form you use, this is only a matter
of personal preference.

The /I switch allows you to control the indenting of commands
from the left margin.  Follow /I immediately by a decimal number
to specify the column in which you wish the first command to
appear.  The default is column 9.

The /W switch allows you to control where QMac wraps multiple-
line macros at the margin.  Follow /W immediately by a decimal
number.  The default is to wrap at column 80.


ERROR MESSAGES
--------------
QMac can deal with many errors in a macro text file by skipping
either a single command or word, or a whole macro.  It will
display a warning message indicating this when it occurs, but
will not stop.

However, if a large number of warning messages occur (by default,
20), QMac will give up processing on that file.  If you have some
"troublesome" macro files that you need to process, you can set
the number of warnings that QMac will tolerate with the /E
command line switch.

Errors in the input text are always indicated by the row and
column where the error occurred, so you can use this to locate
the problem.  If you use QCP to run language compilers from
QEdit, you can install QMac as one of the compilers to take
advantage of this.  Use the line in QCP.DAT:

     .qm  "qmac $N.mac $F B N >$O"  "QMAC "

(This assumes that you always use the extension ".QM" on all text
macro files).

Here is a summary of the possible error messages that QMac can
issue.  QMac will continue after "Warning"'s but will stop after
the first "Error".  The following messages are in approximately
alphabetical order:

     Warning:  Duplicate definition for label <label_name>.

The label named "label_name" was defined in two places.  Remove
one of the definitions, or change one of the labels names.  For
now, QMac will use the first definition of the label.



QMac 2.15 Documentation                                   Page 12


     Error:    Error reading input file
     Error:    Error writing output file

A DOS error occured on reading or writing the file.  Check the
file(s), or the disk(s) on which they reside, for problems.

     Warning:  <command_name> ignored inside macro

Certain commands, such as MacroBegin, MacroRecord, InputCh and
Literal, are not legal inside of a macro (even though they are
legal when assigned alone to a key).  QMac ignores these, but
warns you that it has done so.

     Error:    Input file D:\PATH\FILENAME.EXT does not exist.

Based on the direction you specified with /B or /T, what QMac
determined to be the input file could not be found.  Check the
path echoed here for errors.

     Error:    Input file and output file are the same.

The two filenames point to the same file on disk, please change
one.

     Error:    D:\PATH\FILENAME.EXT is not a valid QEdit
               binary macro file.

When reading from or appending to an existing binary macro file,
QMac checks it for errors.  If there are problems, the above
message will occur.  It will also occur if you accidentally
specify the two filenames backwards on the command line.  It may
also occur if you are using an out-of-date version of QMac.  If
the binary file is too large to load into QEdit, this message
will also be issued.

     Warning:  Label <label_name> not found--jump ignored.

The label to which a jump instruction pointed could not be found.
Check for spelling errors.  A do-nothing jump will be inserted in
place of the erroneous jump, so the resulting macro may not
operate correctly.

     Warning:  Label missing--jump ignored.

No label was found after the jump statement.  A do-nothing jump
will be inserted in its place.



QMac 2.15 Documentation                                   Page 13


     Warning:  Macros cannot be assigned to two-keys.  Macro skipped.

QMac skipped this macro because it was assigned to a two-key.

     Warning:  Macro contains an infinite loop.

QMac found a jump instruction that jumps to itself.  Since this
would loop forever, it warns you about this condition.  NOTE:
not all infinite loop conditions are caught by this, just obvious
ones.

     Error:    Macro file would be too large for QEdit.
     Error:    Macro too long!

The total size of binary macros to be written would be too large
for QEdit to load into its internal macro buffer.  No binary
macros will be written or appended.  Shorten your macros, or
remove some, and try again.

     Error:    Neither file exists.

Neither one of the files on the command line can be found.

     Error:    No macros found in D:\PATH\FILENAME.EXT

None of the text in the input file fit the form of a QEdit macro
definition.  You may get this message if QMac skipped macros in
your file due to other errors.

     Error:    Not enough RAM to process macro file.
     Error:    Not enough memory.

QMac could not load the binary macro file into memory for lack of
space.  Exceedingly rare, as most macro files are very small.

     Warning:  Number ignored. (Put '#' in front of ASCII codes).

You must precede ASCII codes with '#' as of QMac 2.1.

     Warning:  Only first 32 characters are significant in labels.

QMac found a label it thought was longer than 32 characters.  It
will take the first 32 characters of the name and use that as the
label name.

     Error:    Output file D:\PATH\FILENAME.EXT is Read Only!

QMac found that the output file is designated Read Only by DOS,
and thus cannot be written.  Use ATTRIB to change the Read Only
status, or choose another filename.



QMac 2.15 Documentation                                   Page 14


     Warning:  Possible truncation of line.

QMac found a line that might be longer than 512 characters.  This
should never occur if you create all your files in QEdit.

     Warning:  Quoted string not closed at end of line.

QMac found an opening quote but no matching close on the line.
It will close the string at the end of the line and continue.

     Error:    Too many errors.  Aborting!

After 20 warning messages, QMac will issue this message and halt.
This is to avoid cases where hundreds of errors might be caused
by a faulty input file.  The number of warnings QMac will
tolerate can be controlled with the /E command line parameter.

     Warning:  Too many jumps--ignored.

There is a limit of 32 jumps per macro.  If this is exceeded,
subsequent jumps are replaced with "do nothing" jumps.  Remove or
consolidate some jumps and try again.

     Warning:  Too many labels--ignored.

There is a limit of 32 labels per macro.  This message may come
up when processing a label, or when processing a jump.  Remove or
consolidate some labels and try again.

     Warning:  Unknown command <command_name> skipped.

A command "command_name" was found in your macro, that is not
recognized as a valid QEdit command.  Either it is misspelled or
you are using an out-of-date version of QMac.

     Warning:  Unknown key <key_name> skipped.

A key "key_name" was found, that is not recognized as a valid
QEdit key name.  Either it is misspelled, or you are using an
out-of-date version of QMac.

     Error:    Unrecognized command switch 'x'

A switch "/x" on the command line was not recognized.  QMAC ? at
the DOS prompt will print a summary of supported switches.



QMac 2.15 Documentation                                   Page 15


     Warning:  Unsupported op-code <xxx> in binary macro input.

An unrecognized code was found in the binary macro file.  Either
the macro file is damaged, or you are using an out-of-date
version of QMAC.

     Error:    /X value not specified.

The numeric value following a /I, /W or /E switch must
IMMEDIATELY follow the switch, with no spaces between.


ACKNOWLEDGEMENTS & CONTACTS
---------------------------
Special thanks to Karl Brendel, who wrote the original 1.x
versions of QMac.

If you have any questions or suggestions, please contact:

SemWare
4343 Shallowford Road
Suite C3A
Marietta, GA  30062-5022

Voice Phone: [phone]   9 a.m to 5 p.m. E.T., Mon-Fri.
BBS Phone:   [phone],  1200/2400/9600 HST bps, <N81>.
                              24 hours, 7 days per week
FAX:         [phone],  24 hours, 7 days per week.
COMPUSERVE:  71520,67

REVISION HISTORY
----------------
Version 2.08 - Nov-1989
        Complete rewrite.  Faster.  Better error checking.  Key
        names must be in column 1.  Ampersands made optional.
        ASCII codes supported.  Comments made more flexible.  Now
        accepts lines up to 512 characters long.  Many command
        line options added.

Version 2.10 - Feb-1990
        Now require "#" preceeding decimal ASCII codes.
        Jump, JTrue, JFalse supported.
        New commands in QEdit Advanced 2.10, QEdit TSR 1.10, and
        QEdit for OS/2 1.50 supported.

Version 2.10 - June-1990
        Now handles the shorter method of repeating a QEdit
        command. For example:
                          Cursorright 10
                         Is equivalent to:
                  Cursorright RepeatCmd "9" Return

        Both of these statements result in moving the cursor to
        the right 10 times.

Version 2.15 - Aug-1991
        New commands in QEdit Advanced 2.15, QEdit TSR 1.15, and
        QEdit for OS/2 1.55 supported.


                        * * *  end  * * *