home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Black Box 4
/
BlackBox.cdr
/
wordperf
/
macade41.arj
/
MCOMPILE.DOC
< prev
next >
Wrap
Text File
|
1991-08-15
|
16KB
|
323 lines
MCompile.exe
A Utility for Compiling ASCII Text File
Listings of WordPerfect 5.1 Macros
into Executable Macro (.wpm) Files
by
Jeffrey S. Kane, Ph.D.
Performance Sciences International
Summerfield, NC
1. Read the REGISTER.doc, LICENSE.doc, and WARRANTY.doc files distributed
with this macro.
2. Requires:
A. WordPerfect 5.1 (for use of compiled macros)
B. MS/PC-DOS 3.0 or higher
C. An ASCII source file that conforms to the compiler's
structure and syntax specifications.
3. Features:
A. Fast (e.g., less than 4 seconds for a 10K source file
on 386DX-20 machine).
B. Compact .exe file size (10.5 KBytes)
C. Accurate
D. Powerful: accepts source files of unlimited size.
E. Handles either spaces or tabs as formatting characters
at the beginnings of lines (up to first significant
character on any line).
F. Case insensitive: accepts commands in whatever case you
feel like entering them.
4. Installation:
No installation is required other than to copy the
MCompile.exe file to the directory where your WordPerfect
macros reside. As in the case of Macrolst, we recommend
locating MCompile in this directory for the sake of
convenience, there being no inherent technical requirement to
do so.
5. Operation:
A. Structure of Source Files
ASCII text file listings of macros, which we'll
refer to as source files from this point onward, must
conform to an easily achieved structure in order to be
successfully compiled. The structure of a source file
consists of three separate components, as follows:
1) Header: all characters from the start of the file
to the 'STARTMACRO:' code delimiter.
2) Code Delimiter: the word 'STARTMACRO:', including
its terminating colon.
3) Source Code: all characters from the end of the
code delimiter to the end of the file.
The compiler will first search through the Header to
find the phrase,
Macro Description:
All the characters up to a maximum of 39 that occur between
the colon at the end of the above phrase and the first end of
line sequence (ASCII 13ASCII 10, produced by pressing your
[ENTER] key) encountered before the beginning of the
'STARTMACRO:' code delimiter will be used as the macro
description. Thus, if you intend there to be no description
for the macro, either leave out the 'Macro Description:'
phrase altogether, or follow it with an immediate press of
your [ENTER] key.
The compiler then looks for the 'STARTMACRO:' code
delimiter. This delimiter MUST appear before the start
of the source code, or no compilation will occur. Every
character after the code delimiter to the end of the
source file will be compiled into macro code.
To generate an example of how the structure of a
source file should look, use the Macrolst program to
create a source file from one of your existing macros.
Macrolst creates files which are directly recompilable
back to macros (i.e., .wpm files).
B. Syntax of Source Files
1) All macro and keystroke commands must begin with an
opening French brace ({) and end with a closing
French brace (}).
2) In earlier versions of MacroAde the MCompile program
required that the case (i.e., upper or lower) of every
letter between the braces in all macro and keystroke
commands exactly match that used in the display format
of the commands. However, several macro enthusiasts
have suggested that the goal of any external editing
capability is ease of use. To have to observe the
proper case of command characters conflicts with that
goal. Consequently, in this version any mix of cases
may be used in entering any command. However, MacroLst
will continue to translate the commands in a macro in
accordance with WordPerfect's case format conventions.
in WordPerfect.
3) Most of the macro commands are listed and explained in
detail in Appendix K of the WordPerfect 5.1 manual.
The complete list of the commands is presentedd for
syntax reference purposes in the COMMANDS.ref file
contained in the MacroAde package.
4) WordPerfect furnishes no list of the keystroke commands
in the form in which they actually appear in WordPerfect's
macro editor. MacroAde provides the needed list of these
commands in their correct form in its COMMANDS.ref file,
following the list of macro commands. Next to each
keystroke command its WordPerfect code is listed,
which is needed for some macro commands. These
commands must be entered exactly as they appear in
this list EXCEPT for their case or a syntax error will
occur and halt compilation.
5) One special syntax rule that is unique to creating
source files compilable by MCompile concerns the
manner in which non-keyboard characters are entered
to correspond to the use of WordPerfect's 'Compose'
feature. This feature is used to access characters
in WordPerfect character sets above Set 0 (i.e.,
Sets 1-12), although it can also be used for Set 0
if there is some reason to do so (e.g., see below for
the special case of specifying braces as literal
characters, not parts of commands). You can specify
any of these characters in the 13 Character Sets
(see Appendix P of WordPerfect manual) by entering
its code using the following syntax:
[:S,C]
where:
S = the WordPerfect Character Set number (0-
12)
C = the number of the character within the
specified Character Set
For example, to specify the copyright symbol, which
is character 23 in set 4, you could enter:
[:4,23]
NOTE: Even though the compiler accepts certain high
ASCII codes in the above form (e.g., [:0,250]) for
various purposes in the construction of .wpm files,
do not use any other high ASCII characters (i.e., >126)
in your macro if they aren't specifically allowed in
these instructions. WordPerfect's character set 0 only
contains the first 126 ASCII characters; use of others
not authorized here will not be recognized in WordPerfect.
6) The easiest approach to handling spaces and tabs in the
compilation process would be to merely interpret them
directly. However, this approach would make it very
difficult to use editors which expand all tabs into spaces.
One of the most widely used editors--QEDIT--offers a choice
of either the latter sort of tab expansion or a literal
treatment of tabs which displays the tab character but
doesn't execute it. The result of the latter approach is
a very unreadable display since none of the indentation
actually appears. The tab expansion option produces a
readable display but eliminates all the tabs, which would
leave the compiled macro without any indentation formatting.
This can be slightly alleviated by using QEDIT's Tabs Out
configuration option, but that only applies to new lines
inserted in a macro and only deals with space sequences of
one fixed length. A similar problem arises in using the
EDITWP macro to edit macros as WordPerfect documents. This
macro saves the documents via WordPerfect's Text Out feature,
which converts all tabs to spaces, thereby eliminating all
indentation formatting information if the compiler were
designed to interpret all spaces literally. Clearly, an
approach other than literal interpretation of tabs and
spaces is needed.
MCompile intelligently parses all instances of the space
character into either tabs or literal spaces. This enables
MacroLst to produce source files using the expansion of tabs
to spaces (ASCII 32) that are highly readable in any editor.
MCompile will then convert all sequences of 3 or 4 spaces
back to tabs.
The cost of this approach is that with one exception, all
spaces intended to be retained as literal spaces within
the macro must be represented by the ASCII 250 character
or by the [:0,250] character code (if your editor won't
represent ASCII 250). The exception is any space that
occurs between two non-space (i.e., not ASCII 32) characters
and not at the start of a line, as in those separating the
words in comment. These singly-occurring spaces will be
compiled as literal spaces in the macro.
Many editors offer a keyboard macro capability that will
make the use of ASCII 250 much easier. For example, in
QEDIT you can simply edit your keyboard configuration file
(QCONFIG.DAT is its default name if you haven't renamed it)
and assign the following line to any key that you want to
use for ASCII 250:
macro_begin '·'
The character between the single quotes is ASCII 250, which
you can access in QEDIT by holding down the ALT key and
typing 250 on the numeric keypad (actually, on my keyboard
I have to hold down both CTRL and ALT). Once you've changed
the keyboard configuration file, you'll then have to run
the QCONFIG.EXE program, select the Keys option, and then save
the setup in order for the new key assignment to take effect.
7) Tabs and spaces may be used at the beginning of each line
to indent it for formatting purposes. The compiler
interprets all space (ASCII 32) characters that occur
before any other characters at the beginning of a line as
formatting characters and translates all sequences of 3 or
4 such spaces to tabs. If you need to continue a line
containing a sequence of literal spaces (i.e., spaces that
actually need to be in the macro) in such a manner that
would cause one of the literal spaces to start the next
line, and for some reason you can use the ASCII 250
character (e.g., your editor won't allow you access to it),
then represent it and all other such literal spaces with
the [:0,250] character code.
8) After the first non-formatting character on each line
use only tabs, not spaces, to do all spacing for purely
formatting purposes to make the source code easier to
read. The use of spaces for this purpose after the
first non-formatting character in a line will result
in the macro actually entering those spaces in the
document in which the macro is executed.
9) Ensure that the editor you use to create or modify
the source file does not replace tabs with spaces
when its saves the file. Many editors provide
configuration options to control this. For
example, with QEDIT you must set the configuration
for tabs (i.e., by executing QCONFIG and selecting
'Tab Settings' from the menu) to start in Physical
Tab Expansion Mode and in Tabs Out Mode. These are
the first two questions asked in the Tab Setting
configuration process. You should also answer 'No'
to the last question in this part of the
configuration process--'Do you want to start in
Smart Tabs Mode?'.
10) If you want to visibly mark spaces (e.g., for ease
of counting), use ASCII character 250 (FA Hex) or
[:0,250] if your editor doesn't allow entry of high
ASCII characters. This character will be properly
compiled as a space character (ASCII 32).
11) Do NOT use the "{" and "}" characters in any way other
than to enclose a macro or keystroke command within the
macro source code. The compiler assumes that all
occurrences of these characters are meant to enclose
commands and will generate an error and terminate
compilation if they occur without enclosing commands.
This is the only difference from WordPerfect's internal
macro editor, which allows you to use these French braces
as characters having nothing to do with commands.
You can, however, enter non-command related braces
in character code form. Specifically, you can insert
literal braces anywhere in a macro by using the following
codes:
"{" = [:0,123]
"}" = [:0,125]
12) A violation of any of these syntax rules or the
occurrence of an illegal or misspelled command will
cause MCompile to issue an error message and halt
execution. It also assigns a value from 11 to 17
to the DOS Errorlevel variable to designate the
occurrence of a particular error. Checking
Errorlevel is a useful way of checking the
compilation process when MCompile is executed
within a batch file.
C. Once a source file is ready for compiling, the actual
compilation process is invoked by the following command:
MCompile macro(.lst)
Note that the name of the source file on the MCompile
command line may exclude the .lst extension, but will
accept the name with this extension if it is given.
MCompile assumes that any source file has the .lst
extension, but this assumption may be overridden by
explicitly specifying a different extension.
D. If for some reason the compilation fails and a macro of
that name previously existed, the prior version of the
macro will be preserved.
6. Technical support:
Free technical support will be furnished to any licensed user
who calls on weekdays during the hours from 9:00 a.m. to 5:00 p.m.
(Eastern) at the following number: (919) 643-3492
We may also be reached by mail at:
Performance Sciences International
Suite 1250
3001 Latta Drive
Summerfield, NC 27358
