MACRODOC.EXE

A Macro Command Listing Utility

Version 2.01, December 27, 1988

MACRODOC is a program that documents your WordPerfect 5.0 macros. It creates a WP5 document that contains the macro file name, it's description, and the commands used in the macro. The file is named <macro name>.MDC, so if you analyzed the ALTM.WPM file, MACRODOC would create a file called ALTM.MDC . The file is stored in the same drive/directory as the macros. MACRODOC will analyze one or many files at the same time.

WHY USE MACRODOC?

Well, other than the fact that we're sort of proud of our accomplishment, there are some very good reasons. You can, of course, get the same effect by editing the macro in WP5 and then "print-screening" the macro commands. But that's sort of messy and inconvenient. We use MACRODOC because it's sometimes easier to figure out what's wrong with a macro when you can scribble notes on the paper. And you might like to have a printed copy of your macro creations. Maybe the macro you've created is bigger that the box that the macro edit screen uses. Or maybe you'd like to have history copies of macros as you create and enhance them.

You can probably think of some other reasons. And until WPCorp comes up with a macro editor for WP5 (the one in the WP Library won't work), this is a great alternative.

HOW TO RUN THE PROGRAM

MACRODOC is run at the DOS prompt by typing in

MACRODOC

(we assume that you've got the program in the current directory, or that there's a DOS PATH pointing to where the program "lives.")

The SORT.EXE program (which comes with DOS 2.1 and above) is used to alphabetize the names of the macro files you are analyzing. Since the program normally sorts the directory listing of macro files, you need to make sure you have the ability to use the DOS SORT command. If you are not sure, you can test it by typing in the following line (while in any directory).

DIR *.* | SORT > DIRECT.LST

That will create a DOS text file called DIRECT.LST that will contain a sorted list of all the files in the current subdirectory. If you see a message "Bad command or file name", SORT is not available.

If SORT is not available, you have three choices:

1.	Make sure that SORT.EXE is in the default (current) drive/directory.

2.	Make SORT.EXE available by including the DOS directory in your PATH command. If you have a hard disk, and the DOS programs are stored in C:\DOS directory, you'd enter at the DOS prompt:

PATH = C:\;C:\DOS

You can see what your current path is by entering:

PATH

3.	Use the NOSORT option when running MACRODOC:

MACRODOC NOSORT

HOW IT WORKS

MACRODOC first asks you for the drive/directory that contains the WPM files. It defaults to C:\WP50. It then asks for the file name of the macro you want to analyze. If you don't specify a macro name, it assumes you want all of the macro files (*.WPM) in the directory you specified. (Only WPM files are analyzed, no matter what file extension you specify.)

MACRODOC then makes sure that the directory and file names are properly specified. If it finds a problem, it will ask for the directory name and file name again.

MACRODOC builds a SHELL command that makes a sorted directory of the WPM files. (See the note above about the DOS SORT command, and the NOSORT alternative.) This command, when the default values are used (directory C:\WP50, and all macro files), is:

SHELL DIR C:\WP50\*.WPM | SORT > C:\WP50\MACRODOC.DIR

This creates a file (MACRODOC.DIR) that is a sorted directory of the file names. (If you want to see what the file looks like, enter the above command -- without the "SHELL" word -- at the DOS prompt.)

The program then throws away the first few lines of non-file text (5 if sorted, 4 if the NOSORT option was used) and then looks at each WPM file. It gets the description, and writes the file name, file date/time, and description into the <macro name>.MDC file that is created in the directory that contains the macro files. (In our example, the file would be

C:\WP50\<macro name>.MDC .)

MACRODOC then looks at the rest of the macro file to get each command. The commands are internally stored as two bytes, and we use a translation table to convert the codes to their English equivalents.

The result is a file that looks a lot like what you see when you edit a macro in WP5. Here's a simple sample of a MDC file:

MACRODOC -- MACRO FILE DOCUMENTER

10-03-1988, 12:27

Macro file : E:\MACROLST\ ALTB 8-02-88 8:32am

Description : Block a line

Macro commands:

{DISPLAY OFF}{HOME}{HOME}{HOME}{LEFT}{BLOCK}{HOME-HOME-RIGHT/END KEY}

*** end of macro ***

When the program has finished looking at all the macro files, the MACRODOC.DIR file is deleted, and you are returned to the DOS prompt.

There is no limit to the number of WPM files that can be translated (except the limits of disk space, of course). We've tested the program with 114 files. The MDC file is a WP5 document, defined with a DOS Text Printer definition. When you retrieve the file, your default printer definition will be used.

COMMAND LINE OPTIONS

There are three optional commands that MACRODOC recognizes. They can be specified in any order.

NOSORT	Will not use the DOS SORT command to create the MACRODOC.DIR file. Macros will be analyzed in the order that they are found in a directory list.

TEXT	Creates a DOS text file, rather than a WP5 document. If you want to edit the file with WP5, use the Text In/Out command (Ctrl/F5). You can print the MDC files with a DOS PRINT command:

PRINT C:\WP50\*.MDC

HELP	Prints a short message showing the available command line options. No macros will be analyzed if you specify this command line option.

The command line options can be specified in any order. Here's an example:

MACRODOC NOSORT TEXT

This will create MDC text files, and will not use the DOS SORT command.

ERROR MESSAGES

We've tested the program both inside and outside WP5, with different drive/directories specified. You might see an execution error message if there's not enough free memory, if there's not enough disk space to save the DIR and LST files, or if you specify a drive/directory that doesn't exist.

VERSION CHANGES:

1.1 (8/12/88): Release version.

1.2 (9/7/88):

FIXES

* Due to a missing code in the WPCorp Developer's Kit, certain macro programming commands (accessed with Ctrl/PgUp in Macro Edit) did not translate correctly. For instance, {End If} was translated as {reserved}.

The {HRt} code was changed to {Enter/HRt). There was also a spelling error: {Date/Outlin} to {Date/Outline}.

* Line draw characters (and other extended characters) were ignored when translated. All Extended Characters (see the Appendix in your WP Reference manual) are now translated. Box drawing characters will be shown as:

{ExtChar:x,y}

and other extended characters (entered with the Control/V command) will show as:

{^V/ExtChar:}x,y

where "x,y" are the character codes. The extended characters are translated this way because actual characters might not show properly when printing to your printer.

* When defining a macro, pressing the TAB key puts a {Tab} code in the WPM file. When editing a macro, pressing the TAB key will place an ASCII 9 Tab character in the file, and will show as blank spaces in the edit window. (Regular spaces, ASCII 32, are shown with a "center dot" character -- ASCII 250.)

MACRODOC only stores ASCII characters 32-126 in the MDC file, so the ASCII 9 is not stored. If it was stored in the file, and the MDC file is printed, it would be hard to tell the difference between a "space" character and the ASCII 9 character.

The ASCII 9 character could be stored as another character, which we think would be confusing. The space character could be stored as a "center dot" character (like is shown in Macro Edit), and the ASCII 9 stored as regular spaces. But if the MDC file is retrieved into WP5, the ASCII 9 character becomes a [Tab] code, which also confuses the issue. So we think it's best to leave it the way it is -- but we're open to suggestions on how to handle this.

* If the NOSORT option was used on the command line, an error message "Bad file name or number in module Macrodoc at address xxxx:yyyy" occurred. This was caused by trying to open a file with no name (the last line of a DIR command contains the "xx File(s).." text line). Version 1.0/1.1 did not properly trap that line in the DIR file. All macros were translated properly, however.

1.3

* There were two undocumented macro commands (IF EXISTS and ORIGINAL KEY) in the WPCorp developer's kit. These commands are now properly translated.

* Extraction of the macro description is now more accurate.

ENHANCEMENTS

1.2	Version 1.2 now verifies that the WPM file is actually a macro file.

Extended characters are properly translated.

Keyboard macros, file macros, and variables are now translated.

1.3	* Files are more completely identified as macro type files. If non-macro files are found, the program will create an MDC file with a notice that the file is not a macro file.

* Embedded tabs, which can be inserted in MACRO EDIT command to make the macro codes more readable, are now expanded to four spaces as they are in Macro Edit. CR/LF's (Hard Returns) added while in MACRO EDIT are also retained. This gives you more formatted macro text.

* All macro commands are UPPER-CASED, to differentiate between commands and text. Exceptions are the ending codes, such as {CENTER} to indicate a center start, and {center} to indicate an end center.

2.0 (12/1/88)

* Due to missing information in the WordPerfect Developer's Kit, the {TEXT} command came out as {reserved}. It now is properly translated as {TEXT}.

* The {VAR n} code, where n is a number, was incorrectly translated as {Variable Number} without a number. It is now properly translated as {VAR n}, where n is the appropriate number.

* There were some occasional problems with extraneous text or macro codes at the beginning of the MDC file when you analyze a number of macros. The excess codes should not appear in this version.

* MACRODOC now creates a WP5 file as a default, rather than just text files. The WP5 file created uses a DOS printer definition, so when you Retrieve the document, WP5 will convert that to your current (default) printer. You can create text files by specifying TEXT on the DOS command line:

MACRODOC TEXT

* A short help message is shown on screen when you use a HELP option on the command line:

MACRODOC HELP

The program will not analyze macros when you use the HELP option.

NOTE: Because of the first two problems, all registered users were sent a free update to version 2.0. My thanks to those that pointed out the errors, and for our user's patience and understanding.

2.01	(12/27/88)

When we added the capability for creating WP5 documents, we borrowed the code that was written for STYLELST. But we inadvertantly left in "STYLELST", etc. in the top part of the WP5 file (the text file said "MACRODOC" like it was supposed to. We also forgot to note on the closing screen that a WP5 file was created (it said "DOS Text file" when it really wasn't).

So we fixed those two minor annoyances, and made the screen text more centered. We also added a command to add color when you have that capability.

(Thanks to Nate Salsbury for pointing out our little error.)

FUTURE ENHANCEMENTS, POSSIBLE PROBLEMS

Almost all of the macro commands are decoded, we think it's close to 99 44/100% (us and Ivory!). There might be some very obscure combinations of macro commands that could be decoded incorrectly. (For instance, the {TEXT} command we found out about after we released version 1.3, and the two commands that were not previously documented by WPCorp made it into version 1.3). But we think that you'll find MACRODOC very useful for most of your macros. We tested it with many of our own macros, along with those created by WP5 Macro keyboard definition file.

The translation parameters used as they are described in the WordPerfect Corporation "WordPerfect 5.0 Developer's Toolkit." Some command codes are {reserved}, and if WPCorp changes them, we'll add those codes if we hear about them. If you know about errors in that documentation, or additional features added by WPCorp, please contact me.

If you have a problem with any macro file not translating properly, send me the macro file and a description of the problem and we'll see if we can figure out how to fix the problem. An example might be if WPCorp adds new macro commands.

IF YOU HAVE PROBLEMS

While we tested this program quite a bit, it's possible that you might have problems. Some things to check: did you specify a drive/directory that actually exists, is there enough room on the disk for the DIR and MDC file, do you have too many files in a directory (there's a limit of about 112 files allowed by DOS in the root directory of a floppy disk).

If you see a quick message: "Bad command or file name", then you probably do not have the SORT program available. See the discussion above on the alternative NOSORT command, or the other choices.

If you get an error "Can't find the MACRODOC.DIR file", run the DIR command shown above (don't enter the SHELL text). If your version of DOS doesn't support the "| SORT" command, make sure you use the NOSORT option on the command line.

SEMI-LEGAL STUFF

This version (2.01) is released to the public as "shareware." We have copyrighted the program, although you can use it for your own personal use. Of course, you can't include it in any product you sell without written permission from us.

If you find the program useful, we suggest that you register it with us by paying the $15.00 registration fee.

Although we've extensively tested MACRODOC, and there's no "damaging" code, we can't be responsible for any damage to your system caused by this program or variations of the code. (With the brain-damaged programmers out there that are writing virus programs, we trust that you'll perform the necessary precautions when dealing with all programs you download.)

A SHORT PLUG FOR MACROLST, OUR OTHER MACRO PROGRAM

We've also written MACROLST, a program that will give you a list of macros and their descriptions. We've found it to be very useful to keep track of all the macros we've written. It works very similar to MACRODOC, and is available at no charge.

Here's a short extract of how the file looks when it's done:

SORTED MACRO FILE DESCRIPTIONS

10-02-1988, 09:41

Macro File Date Time Description

C:\WP50\ ALTB 8-02-88 8:32am Block a line

C:\WP50\ ALTC 8-04-88 8:10am Center a line

C:\WP50\ ALTD 8-01-88 10:45pm delete a whole line

...etc.

You'll find it on CompuServe (MACROL.ARC) (others have written similar programs). You can also get a copy by sending me a disk (with return postage and mailing label) to the address below. We'll also include the latest version of MACRODOC on the same disk.

STYLELST -- OUR STYLE LISTING PROGRAM

We've also written a program similar to MACROLST for style files. STYLELST will look at individual style files and extract the style name and description. The output will be similar to MACROLST, shown above.

STYLELST is available on CompuServe in the WPSG forum, DL0, as STYLEL.ARC. You'll also find MACRODOC (MACROD.ARC) and MACROLST (MACROL.ARC) there.

STYLEDOC -- OUR STYLE DOCUMENTER

Our next project, after STYLELST, is a style documenter that works similar to MACRODOC. STYLEDOC will translate the styles into a text file, so you'll have written documentation for your styles, too. Look for STYLEDOC on in the WPSG forum on Compuserve, or on your friendly neighborhood BBS. STYLEDOC will also be shareware, with a $15 registration fee.

A SPECIAL DEAL

If you want to get registered copies all four programs, (STYLELST, STYLEDOC (if available), MACROLST, and MACRODOC), send along a $25 registration fee (that saves $5) and a disk in a mailer. We'll send back the latest versions of those four programs, and our thanks.

HOW TO FIND ME

We're interested in your suggestions on how to improve the program, and if you have problems. The easiest way to contact me is electronically. You can leave a message on CompuServe (71331,514) or on the Time Traveller BBS system (916) 739-8386 (2400-N-8-1). We'll try to respond quickly (We're on Compuserve daily, and on Time Traveller weekly).

We'll be posting information about new versions of this and other programs on CIS when they are ready.

You can also contact me by mail at:

PLACER COMPUTER SYSTEMS

3488 Corwin Court, Loomis, CA 95650

Rick Hellewell (CIS: 71331,514)

---30---