💾 Archived View for mirrors.apple2.org.za › archive › ground.icaen.uiowa.edu › apple8 › Appleworks ›… captured on 2023-01-29 at 10:45:59.
-=-=-=-=-=-=-
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 <cmd> 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 <link> can happen. If you are new to UltraMacros
then you don't have a clue what the <link> command is. Suffice to
say that the manual will tell you that you can have only one <link>.
However, if you keep track of things you can have multiple <link>
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 <find> 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: <Launch STRING VAR>.
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.