MACRODOC.EXE

A Macro Command Listing Utility

Version 2.01, April 5, 1989

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.)

2.01 (4/5/89) Changes to documentation only.

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.

A SHORT PLUG FOR OUR OTHER PROGRAMS

MACROLST, THE MACRO REFERENCE LIST

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 STYLEDOC, and is available at no charge.

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

MACROLST - MACRO FILE LIST/DESCRIPTIONS

Macro files: C:\WP50\*.WPM

As of: 04-05-1989, 3:39 PM

MACRO NAME	SIZE	DATE	TIME	DESCRIPTION

ALTB.WPM	85	8-02-88	8:32am	Block a line

ALTC.WPM	84	8-04-88	8:10am	Center a line

ALTD.WPM	92	2-24-89	2:22pm	delete a whole line

...etc.

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.

STYLEDOC -- OUR STYLE DOCUMENTER

STYLEDOC is a program that documents your styles, much the same as MACRODOC documents macros. It translates styles into a text or WP5 file, so you can really see how those styles are written.

STYLEDOC is also shareware, with a $15 registration fee.

A SPECIAL DEAL

If you want to get registered copies of the latest versions of all four programs, (STYLELST, STYLEDOC, 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.

You can also find the latest versions of all four programs on CompuServe's WPSG Forum (GO WPSG) in DL0. Look for MACROL.ARC, MACROD.ARC, STYLEL.ARC, STYLED.ARC.

HOW TO FIND ME

We're interested in your suggestions on how to improve the program, and if you have problems. The fastest 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 also have a fax number, it's available evenings only at (916) 652-3368. (We have an Intel Connection Coprocessor; if you have one too, you can send us a file as well as a fax. Include your fax number, and we'll "fax you back".) We'll try to respond quickly (we're on Compuserve daily, and on Time Traveller weekly). You can also use the comment form at the end of this document if you wish.

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

You can contact us by mail at:

PLACER COMPUTER SYSTEMS

3488 Corwin Court, Loomis, CA 95650

Rick Hellewell (CIS: 71331,514)

FAX (evenings only): (916) 652-3358

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

Product Registration Payment Form

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

To order your registered copies of MACRODOC or STYLEDOC, please fill out the form below. Use your mailing address only, please. Shipments are normally made via U.S. Mail. All orders shipped in 5 1/2" format (360K) only.

Date: _____________

Name: _____________________________ Title: ___________________

Company: ________________________________________________________

Address: ________________________________________________________

_________________________________________________________________

City: ___________________________________________________________

State/Country: ________________________ Zip: ____________________

Phone Work: (_____) _____ - ______ Home: (_____) _____ - ______

Method of payment: Please complete the worksheet below and choose one of the payment options indicated. California State residents must add sales tax. ALL CHECKS AND MONEY ORDERS MUST BE DRAWN ON U.S. ACCOUNTS ONLY.

|================================================================|

|	|	| Cost	| Total	|

| Qty	|	Description	| per unit	| Cost	|

|================================================================|

|	|	MACRODOC program only	|	$15.00	|	|

|	|	(includes MACROLST)	|	|	|

|	|	STYLEDOC program only	|	$15.00	|	|

|	|	(includes STYLELST)	|	|	|

|	|	MACRODOC/STYLEDOC package|	$25.00	|	|

|	|	(incl. STYLELST/MACROLST)|	|	|

|================================================================|

|	California residents add sales tax |	|

|--------------------------------------------|---------|

| Shipping Cost if Overseas, add $10.00	|	|

|======================================================|

|	TOTAL	|	|

|======================================================|

Payment type	[ ] Check enclosed	[ ] Money Order

(Funds drawn on U.S. Banks only)

Signature: ______________________________________________________

*****************************************************************

Send all items to:	Placer Computer Systems

3488 Corwin Court

Loomis, CA 95650

*****************************************************************

Thanks for your registration!

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

PROGRAM COMMENT FORM

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

Your comments about this software and documentation are welcome. Please take the time to fill out this form. You can mail or fax this form with your comments.

Name: _____________________________ Title: __________________

Company: _______________________________________________________

Address: _______________________________________________________

________________________________________________________________

City: __________________________________________________________

State/Country: ________________________ Zip: ___________________

Phone Work: (_____) _____ - ______ Home: (_____) _____ - ______

MACRODOC Version Number: _____________	Date: __________________

MACROLST Version Number: _____________	Date: __________________

STYLEDOC Version Number: _____________	Date: __________________

STYLELST Version Number: _____________	Date: __________________

________________________________________________________________

________________________________________________________________

________________________________________________________________

________________________________________________________________

________________________________________________________________

________________________________________________________________

________________________________________________________________

*****************************************************************

Send all items to:	Placer Computer Systems

3488 Corwin Court

Loomis, CA 95650

U.S.A.

(Fax number, evenings only: (916) 652-3368)

*****************************************************************

LICENSE AGREEMENT

The MACRODOC/STYLEDOC(R) Products are NOT "Public Domain" and they are NOT "Freeware". MACRODOC/STYLEDOC are copyrighted software products developed and owned by Placer Computer Systems located in Loomis, California, U.S.A. Placer Computer Systems grants you without charge the right to reproduce, distribute and use copies of this version of our MACRODOC/STYLEDOC shareware software products, subject to the limitations specified below, and on the express condition that you do not receive any payment, commercial benefit, or other consideration for such reproduction or distribution, or change this license agreement or the following copyright notice which appears in the software, documentation, user interface, menus and magnetic media: (C) Copyright 1988,1989 by Placer Computer Systems. All rights reserved worldwide.

Limitations: You may make and keep one (1) back-up copy of the software for your personal use, provided that (i) you copy all the copyright, trademark, and other information indicated on the initial screen display (or on the diskette label, for the registered version disk) onto your backup diskette label, and (ii) you have registered. Also you may distribute copies to other persons, but solely for their evaluation (i.e., to decide whether to continue using the product and therefore register) and solely for evaluation by such other persons during that thirty (30) day period. MACRODOC/STYLEDOC must NOT be sold or otherwise provided as part of a larger system, or as a part of a more inclusive product or service, without express written consent and licensing from Placer Computer Systems.

The rights to receive any such financial or other benefit, and to modify the product or employ its components in any kind of derivative work, are reserved exclusively by Placer Computer Systems. Support from users enables us to develop additional features and future versions of the MACRODOC/STYLEDOC products.

Registered users benefit from enhanced technical support, notice of new products, and bulletin board access. Contact us at:

PLACER COMPUTER SYSTEMS

3488 CORWIN COURT

LOOMIS, CA 95650

(916) 652-7425

CompuServe: 71331,514

FAX (evenings only): (916) 652-3368

Also, please feel free to contribute your ideas regarding desired additional product features and functionality.

THIS PRODUCT IS LICENSED "AS IS" WITHOUT ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, PERFORMANCE, OR OTHERWISE; ALL WARRANTIES ARE EXPRESSLY DISCLAIMED. BY USING THE MACRODOC/STYLEDOC PRODUCTS, YOU AGREE THAT NEITHER PLACER COMPUTER SYSTEMS NOR ANY OFFICERS, DIRECTORS, EMPLOYEES, SHAREHOLDERS, AFFILIATES, OWNERS, OR OTHER RELATED PARTIES WILL BE LIABLE TO YOU OR ANY THIRD PARTY FOR ANY USE OF (OR INABILITY TO USE) OR PERFORMANCE OF THIS PRODUCT, OR FOR ANY DAMAGES WHATSOEVER WHETHER BASED ON CONTRACT, TORT OR OTHERWISE. EVEN IF WE ARE NOTIFIED OF SUCH POSSIBILITY IN ADVANCE. (SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THE FOREGOING LIMITATION MAY NOT APPLY TO YOU.)

You may not reverse-engineer, disassemble, modify, decompile or create derivative works of the product. You acknowledge that the products includes certain trade secrets and confidential information, all of which are the copyrighted intellectual property of Placer Computer Systems. MACRODOC/STYLEDOC are registered trademarks of Placer Computer Systems. All rights are reserved worldwide. IBM, PS/2 and Personal System/2 are registered trademarks of IBM Corporation.

RESTRICTED RIGHTS LEGEND

Use, duplication or disclosure by the Government is subject to restrictions as set forth in sub paragraph (c) (1) (ii) of the Rights in Technical Data and Computer Software clause of DFARS 252.227-7013. Placer Computer Systems, 3488 Corwin Court, Loomis, CA 95650. (916) 652-7425