What are these? These are macro and data files needed to generate a manual for using and writing macros in AppleWorks for the Apple ][ (not the Mac or the AppleWorks GS program). It describes UltraMacros 4.x which can be used with AppleWorks versions 3.0 through 5.1. This manual was written because there is no single source of documentation for UltraMacros 4.x. The documentation that came with UltraMacros 4.0 described the changes and additions to Ultramacros 3.0. It depended on the user also having Ultramacros 3.0 and its associated documentation. What is Required to Generate the Manual? 1. AppleWorks 3, 4, or 5 with UltraMacros 4 installed. 2. At least 1 Meg of memory. Needed because all four of the Chapter files need to be loaded at the same time so the macros can process them. 3. AppleWorks must be configured so that when: zoomed in on a DB (Single Record Layout), the cursor is on the last record of the DB, an oa-down (Open Apple and Down arrow keys), causes a blank record to be created. (Auto-Add DB Records at End). From Bud Simrin: For AW 5 oa-Q oa-S will bring up the "Standard Settings" window. Item 14 is for data base options and #1 in that selection is the toggle for adding or not adding. You want "Yes." For AW 4 oa-Q oa-S brings up the "Standard Settings" and "#10 Miscellaneous," brings up a list of options. Here "#7, Auto Add..." is the toggle. For AW 3 there is not an option that I can find. However, AW 3 works from my experiments so it appears to be the default. What are we trying to do here? We are providing a "Do it yourself" UltraMacros 4.x manual. "Do it yourself" means that you will be printing the manual on your personal printer after generating the source from the Chapter files we provide. As you might guess, the number of pages can differ between two models or makes of printers so it is impossible to pre generate the Table of Contents (TOC), Command Index (Index of UltraMacros commands), and General Index (Command Index plus other stuff). You might wonder why you have to generate the source. There are two interrelated answers: 1. Your printer (and any margin changes you might make to the Chapter files), will more than likely print a different number of pages for each chapter. 2. The number of pages for Chapter 1 need to be known so we can set the first page of Chapter 2, the number for Chapter 2 are needed for Chapter 3, etc., etc. The way it works is quite straightforward and automatic. There are chapter files i.e., CH0x, which a macro reads from disk and the name changed to CH0x.TOC. Another macro then scans through the file picking out the TOC items and copying them into a DB file. These entries will be either section headers or a command description. The DB will have a TOC entry for both types, while commands will also populate a "Cmd" category so the Command Index can be extracted from the DB. Once that is complete the macro re-scans the file looking for General Index items. If they turn out to be a command, then a reference is added to the already present entry. If not a command or it is a deleted command that we wish to inform you about, then the item gets its own DB record. It is this DB that other macros use to generate the Table Of Contents, Command Index and General Index files. It is those files plus the CH0x.TOC files that you will print Note: A file, named ErrorLog is created for each step of the process. If the macros run into trouble with a particular entry, they will leave you notes about the problems they encountered. At the end of both sa-A and ba-A, ErrorLog will be checked for entries. If any errors are present, you must deal with them i.e., either change the length of an entry or perhaps change the margin settings back to their original values. You would clear the Desktop of all files (saving none) and rerun the macros starting with sa-A. Where do we put these files? This is a difficult question to answer since this file is part of the archive and you have already unpacked it to get this far. However, all the files in this archive are contained in a folder named "Manual," so the archive can be unpacked to a partition of your HD or 3.5" disks. 1. If the chosen partition is named "Hard1" then unpacking the archive will unpack the files to /Hard1/Manual/..." 2. When you unpack the archive into "/Hard1/Manual" there will be a folder named "Macros" included i.e., "/Hard1/Manual/Macros/..." If you do not have a hard drive then you must unpack the archive onto two 3.5" disks. 1. The first disk must contain these files and no others: CH01, CH02, CH03, CH04, DB.1, DB.AW3, TableOfContents, GeneralIndex and CommandIdx. These last three are empty except for margin settings. 2. The second disk will contain all the other files in the archive which will consist of the following: AA.Readme, KeyChart, MACROS, Try, Try.Docs, TryDB, and TrySS. MACROS is a folder and it contains: Mac.AllPossGen, Mac.AllPossible, Mac.Contents, Mac.DoubleSide, Mac.KeyChart, Mac.TF1, Mac.TF2, Mac.TF3, and Mac.TocCmdIdx. What are the files on this disk? This is a collection of files that allow you to make your own UltraMacros reference manual. The files are: 1. CH0x files, one for each chapter i.e., CH01 is for chapter 1, CH02 for chapter 2. I'm sure you have the rest figured out :-) 2. DB.1, a DB file that is the prototype for the TocCmdIdx DB file i.e., DB.1 is loaded and renamed. For AppleWorks 3 there is a file DB.AW3 that performs the same function for AW 3 since AW 5 DB files cause AW 3 to crash. The program chooses between the two so you don't have to do anything special. 3. Three "Try" files: Try, TryDB, and TrySS. The Try file is a WP file that has a basic set of macros to assist in compiling the example macros from the CH0x files so you can see for yourself how various macros work. Since some of the macros only work in DB or SS files the other two (TryDB and TrySS), files are provided. 4. A file "KeyChart" that lists all possible ASCII values (American Standard Code for Information Interchange). There are 128 ASCII characters codes, each with a low and high value for a total of 256 character codes. The high value represents the 'oa-key' command and the low value represents normal text i.e., a key without oa- being pressed. This is the same chart that appeared on page 101 of the UltraMacros version 3 manual. This chart is needed for cases where a macro asks the user to press a key :A=key : when the key is pressed its numeric value is placed in the variable A. Using "KeyChart" you can write a macro that will decipher which key was pressed. 5. TableOfContents, GeneralIndex, and CommandIdx are empty except for margin settings. You can change the margin settings, however, if you make the margins larger there is a chance that one or more entries will not fit on a single line so an entry will be made in ErrorLog and a warning message printed on the Index being generated. If this happens you will have to either shorten the entry in the CH0x source file or put the margins back to the values they originally had. In either case, remove all files from the Desktop and rerun the sa-A macro. 6. A folder named "Macros" which contains source to the macros used to generate the manual. They will be discussed in the next three numbered steps. 7. Macro file "Mac.AllPossGen" which generates another file, "Mac.AllPossible," which is a listing of all possible UltraMacros names i.e., sa-D, ba-D, sa-!, etc. (NOTE: If you do not understand the nomenclature sa-D, ba-D, etc., then see the file CH01 and the section headed "So What is a macro?" Read the 30 or so lines that follow.) Since there are reserved macro names, not all possible can be used. These are commented out in Mac.AllPossible. See the comments in the beginning of Mac.AllPossGen if you would like to redo the making of Mac.AllPossible. 8. Macro file "Mac.KeyChart" generated the file KeyChart mentioned earlier. You can examine it to see how it really was an easy thing for UltraMacros to do. 9. Mac.TocCmdIdx generates an invisible task file that is called by Mac.Contents to generate the TOC, CommandIdx, and GeneralIndex files. The Big Picture You need to change a line on or about line 40 in Mac.TocCmdIdx to something that gives the pathname where you have placed the CH0x files: #ManualPath = "/H2/UM.MANUAL/Manual" Keep the name as short as possible since 64 characters is max for ProDOS. Step by Step A. The macros need to know where you have stored the CH01 through CH03 files. This can be on a hard drive (HD) or a 3.5" disk. It cannot be a 5.25" disk because there isn't enough room to hold them. B. On my system they are stored at "/H2/UM.MANUAL/Manual" This is called a "Complete Pathname" because the path begins with a slash "/" C. You need to replace "/H2/UM.MANUAL/Manual" in Mac.TocCmdIdx with the complete pathname for your system where you have stored the CH0x files i.e., "/MyHD/Manual" Save the file. See the previous section titled, "Where do we put these files?" for a discussion of hard drive versus 3.5" disks. 9. Macro file "Mac.Contents." This is the biggie. It generates a file TocCmdIdx (Table Of Contents and Command Index), which is a DB file. Before you can do this you must view the top part of the Mac.Contents file in order to change one thing to fit your system. In this case it is the name of the printer that you will use to print the manual. The Big Picture Look for the following on or around line 50 and change to something that makes sense for your system and save the file. #UltraPrinter = "DeskJet Port" //Case counts here NOTE: // begins a comment. If your printer name is so long it causes the line to word wrap to the next line then simply nuke the comment. Step by step A. What is needed is the name of the printer on your system that will be used to print the manual. On my AW 5 it is "DeskJet Port" B. To obtain the exact name of that printer you need to be in a WP document. C. Press oa-P, select "Beginning" and then press Return. D. At this point you are looking at the list of printers defined for your system i.e., 1. DeskJet Port 2. DeskJet Land 3. ImageWriter II, etc., etc. E. Simply write down the name of the printer you want to use to print your copy of the manual. Pay attention to upper and lower case and any embedded spaces in the name. F. As stated before, on or about line 50 of the file Mac.Contents find the line: #UltraPrinter = "DeskJet Port" G. Replace "DeskJet Port" with the name you selected in step E. Note that the name must have a double quote immediately before and after as shown for "DeskJet Port" Save the file. H. Here at the end we put a "confusion" factor. Later on in this file you will be told to remove the SC 1 definition from the designated printer. Another approach, if you have room, add a temporary printer to print this manual this is identical to the one selected above with the SC 1 definition removed. 10. Mac.TF1, Mac.TF2 and Mac.TF3. These three files are used to demo how more than one can happen. If you are new to UltraMacros then you don't have a clue what the command is. Suffice to say that the manual will tell you that you can have only one . However, if you keep track of things you can have multiple commands. 11. Mac.DoubleSide is a macro package that allows you to print on both sides of an HP inkjet or the ImageWriter dot matrix printer. The macros will probably work with other brands of inkjet and dot matrix printers but I have not been able to try others. If you feel that you need more documentation that is contained here, then consult the macro package. Hopefully you will find the documentation suitable for you needs. Load the file CH01 and search for: "Creating your very own UltraMacro," and read that section. Pay special attention to the ba-C macro. If you don't have such a macro in your own macro source file(s), then I predict one will show up in the near future. ============ In the following you are asked to compile Mac.TocCmdIdx and Mac.Contents in that order. This is so you can call sa-A in Mac.Contents to start the process of generating the manual. When that completes, and if there are no errors in ErrorLog, macro ba-A is automatically called to generate the three index files. Compile Mac.TocCmdIdx using the step-by-step approach given in CH01 or by the ba-C macro if you compiled the Try file without launching some other macroset that doesn't define ba-C. After the first compile of any of the macros in this package (except Mac.AllPossible), you can use its ba-C macro and the ba-C macro of any other macro file you compile from this package until you launch your default macroset or reboot AppleWorks. Save the compiled output to disk for launching at a later time by sa-Ctrl-T. Compile Mac.Contents and save the compiled output for later launching by sa-Ctrl-T. Remove both Mac.Contents and Mac.TocCmdIdx from the desktop. File CH01 may be on the Desktop because you were reading the documentation you were instructed to read. It can remain since it will be used soon to create file CH01.TOC. The bottom line here is that the sa-A macro will put 10 files on the desktop (two of which will be automatically deleted if no errors ensue during macro execution). I have tested putting CH01 on Desktop #2 and then starting sa-A with Desktop #1 active. Everything worked fine, but I'm not sure when the command was modified to look on all desktops. So, stick with one Desktop with room for at least 10 files. At this point press oa-Ctrl-X and you will enter the debugger. (See NOTE 1:), Looking at the right hand lower part of the screen you will see: "Name: xxx" where xxx is the name of the currently active task file. In order to proceed xxx must be "Contents." If it is not and you have compiled both Mac.TocCmdIdx and Mac.Contents and saved their output using sa-Ctrl-T, type ba-L which will load the default macros (if they are not already loaded). If the default macros loaded, then follow this with another ba-L to bring up a list of task files. (See NOTE 2:). Choose "Contents." NOTE 1: If you have a IIgs then you can use either oa-Ctrl-X or oa-Clear to enter the debugger. Neither is better, but oa-Clear takes less fingers. NOTE 2: If the ba-L macro is not defined in your default set you will have to go to CH03 and search for text: . Note that there are two variants of the ba-L macro. The one that appears in your default macros and thus brings up a list of launchable task files and the one that appears in all of your task files which simply launches your default macro set. Another option is: 1. oa-Esc and select Ultra Options. 2. Select either "Launch a Task file" or Launch default macros." The files CH01 through CH04 have margin settings of: TM = .5", BM = .2", LM and RM = .5". This works out fine for my printer, a HP 500 InkJet. You might try printing the first couple of pages of CH01 on your printer to see how it comes out. Now is the time to change margin settings if you need to change. Changing anything in the CH0x.TOC files will throw everything off. Saying it another way. Change the margins in the CH0x files before running the macros. Furthermore, if you have a dot matrix printer, you might want to use the "classic" IW settings of: TM = 0, LM and RM your call, and BM = the sum of the top and bottom margins (normally 2 inches). This allows you to position the paper in your printer and know exactly where it will begin printing on each page. At this point you should remove the AA.ReadMe file from the Desktop in order to cut down on clutter. The Desktop should be empty at this point. (Any CH0x files can remain and if you insist, so can the AA.Readme. The crucial thing to keep in mind is that the macros will put 10 files on the Desktop so make sure there are enough empty slots left in the current Desktop.) Assuming that the Mac.Contents package is active, call macro sa-A to generate DB file TocCmdIdx. If Mac.Contents is not active then call macro ba-L to load the default macros. Then call ba-L again and select "Contents" from the list of task files. Then call sa-A to start the process. TocCmdIdx has to be generated first. This DB file has the information needed to build a Table of Contents file (TableOfContents), a Command Index file (CommandIdx) and a General Index file (GeneralIndex). This is NOT a quick process. Best to start the process and then go watch the evening news for 15 minutes or so for sa-A and another 15 minutes for ba-A. The actual numbers are for my IIgs 8Mhz Zip: sa-A = 16:39 and ba-A = 16:12. For my G4/450 Mac running Bernie: sa-A = 6:13, ba-A 5:25. So, if you have neither of the above - consider starting the macros and going to Disney world ;-) In the examples shown here the Command Index and the General Index look similar. Not surprising since it is the OR of the Command Index and the other "things" that we thought ought to be in an index. The Table of Contents is generated in a AWP file. Here is what a few of the lines at the top look like: Table of Contents Page ====================================================================== CH01.TOC Chapter 1 Getting Started .................................. 1 UltraMacros Tutorial ......................................... 1 What is This? ............................................. 1 Main Sources For This Manual: ............................. 1 Installing UltraMacros .................................... 2 So What's a Macro? ........................................ 2 IIgs One-Key Macros .................................... 2 Recording Your Own Macros .............................. 3 The command index is generated in a AWP file. Here is what a few of the lines at the top look like: File Command Page Line # ====================================================================== CH03.TOC () ........................................ 57 1528 CH03.TOC adb ....................................... 39 324 CH03.TOC Ahead ..................................... 43 590 The General Index is generated in a AWP file. Here is what a few of the lines at the top of the file look like: File Index Page Line # ================================================================= CH03.TOC () ..................................... 57 1528 CH04.TOC .AddMany ............................... 112 1927 CH04.TOC .AddMenu ............................... 112 1949 CH04.TOC .AndBits ............................... 137 3529 CH04.TOC .AskYN ................................. 84 121 What's next? When macro sa-A finishes generating the CH0x.TOC files and they are all on the desktop along with TocCmdIdx DB, AND there are no errors in ErrorLog, sa-A will call ba-B to complete the process. When complete there will be seven AWP files on the Desktop: CH01.TOC through CH04.TOC, CommandIdx, GeneralIndex, and TableOfContents. In addition there will be one DB program, TocCmdIdx. Save all eight files to disk. Now you can begin printing your manual out. (NOTE: You want to print the CH0x.TOC files NOT the CH0x files.) See #2 and #3 below for the two methods available to you. 1. You must temporally remove any "Special Code 1" settings you have for the printer you are going to use since the SC 1 is used to mark certain items that will go into the TocCmdIdx DB file. Once the manual has been printed you should reinstall the SC 1 settings (Many folks use SC 1 as a "Begin Italics" marker.) 2. Use AppleWorks to print the manual, CH0x.TOC, TableOfContents, CommandIdx, and GeneralIndex files. At this time the manual files total 153 pages. The other three files are 8, 5, and 6 pages respectively. As you might guess, the Table of Contents should come first, CommandIdx second, manual third and GeneralIndex at the end. (You can put the sections in any other order that pleases you.) 3. Use the macro package Mac.DoubleSide to print the above as double sided pages on either a single sheet printer (HP InkJet), or a dot matrix printer (IW I, IW II, etc.). If you decide to use Mac.DoubleSide then you know the drill i.e., load the file, ba-C (Note:), sa-Ctrl-T and sa-esc to see what macros are available. For Mac.DoubleSide there are two that you are interested in once it has been compiled: 1. sa-P to print the current file. Hint: If using a dot matrix printer, eject a blank sheet before starting to print. This will make it easier to position the page when you reinsert the paper to print the even pages. The menus should lead you through the process. However, if you have questions, take a look at the documentation at the beginning of Mac.DoubleSide. 2. If printing on a continuous feed printer (ImageWriter), be sure and tear the paper at least one blank page after the last odd page that was printed. It is needed to keep the printer from seeing the no paper alarm while the last even page is printing. 3. ba-L to launch your default macros when done printing. Note: If ba-C didn't work, don't come crying to me. I've been begging you to copy that sucker into your default macros. Now you have to go back to CH01 and follow the bouncing ball one more time on how to compile a macro package. Final Actions Once the manual is printed to your satisfaction then you should consider removing task files "Contents" (a system file) and "TocCmdIdx" (a binary file) from the folder where the AppleWorks program resides.