ObiWan is dedicated to beta testers and freeware and shareware authors.
“ObiWan is a must-have”
- Australian&New Zealand MacUser, Pg 88, Nov 1993.
What ObiWan Does
ObiWan is a general help system. ObiWan gives you access to a database through a floating window which you can pop up at any time in any application. Portions of the information can then be sent to the front window as if you had typed it.
Although you can create your own databases, the main use of ObiWan is to access the provided databases, which include:
Force: Procedures, traps, global variables, errors and most of the System 7.6 API.
Java: A guide to the Java class libraries.
Perl: Perl commands.
Words: A word list, useful for checking your spelling.
HTML: A memory guide for HTML (v3.2), which lists valid attributes, whether a close tag is required, and other tags that a tag may contain.
Translation Databases: A variety of English translation dictionaries, described in more detail below.
It is hard to overemphasise the convenience and speed of ObiWan. Index searching is instantaneous, the text output is universal, ObiWan is always available and (new in v5.1) the Web Lookup feature adds to ObiWan’s power.
Features
• BBEdit 4.5 supports ObiWan as a Reference Engine
• The Force file includes all the System 7 information, including Universal Interfaces.
• The Force database is quite up to date, including lots of the new managers.
• The Force database includes page numbers for Inside Macintosh and New Inside Macintosh.
• Any number of databases may exist, only one of which is active at any time.
• First word searches are instantaneous, general searches are very quick.
• Searches may be redirected to the web to get more information.
• Databases are plain text files and can be edited at any time they are not active.
• Databases are reindexed automatically when the file size changes.
• Database file size is unlimited.
• Databases can have any number of entries.
• Uses Internet Config settings.
• English to French, German, Italian, Latin, Portuguese and Spanish dictionaries
Caveats:
Clicks occasionally get lost. This can be fixed by installing Matt Slot's TSM Fix extension.
Delete keys typed in to ObiWan also go into a DA window if a DA is front-most.
The Finder doesn't like having keys dumped at it for some reason.
Using ObiWan
Make an alias to ObiWan and drop it in the Startup Items folder in your System folder. Launch it.
ObiWan silently waits in the background for you to press cmd-` at which time it will pop up a window and let you find entries in the database. Type cmd-` (hold down the cloverleaf key and press the back-quote key (`)). Read the help there, or type "a" and a return to redisplay the help text. Click on the arrows to move through the database. Double-click on words to find their entry.
The buttons and their respective keys are, from left to right:
Lookup <return>
Search Anywhere <shift-return>
Web Search <option-shift-enter>
Previous Entry <cmd-,>
Next Entry <cmd-.>
Jump Back <cmd-[>
Type Word <cmd-enter>
Type Line <cmd-option-enter>
Type Procedure <cmd-shift-enter>
Type Entire Entry <cmd-option-shift-enter>
Play sound at launch (toggles the preference) (not displayed above)
Play sound at invocation (toggles the preference) (not displayed above)
About
Change Database or Parse Procedure <option-return>
NOTE: The startup and invocation sounds have been removed to avoid any copyright problems.
Some of these commands need a little explanation:
Lookup - Uses the Index to do very fast searches.
Search Anywhere - Scans the entire database. Still quick, but not instant like the Lookup command.
Web Search - Dispatches a search URL to your Web Browser (as defined in Internet Config) which does a search on the current entry. The URL varies depending on the Database.
About the Force database
The Force database is partially produced by parsing the files which I have licensed from Apple. Thanks to Rick Fleischman, Barbara Napier, and Apple Computer, Inc. for waiving the fee to allow the Force file to be distributed. The Force file contains all the System 6 and 7 procedures, constants, errors, and global variables. You can find these by opening ObiWan (cmd-`), typing in the start of the name (eg HOpen) and pressing return. You can then insert the routine into THINK Pascal or C or MPW by clicking the third insert button (the one that looks like a procedure) (or by typing cmd-shift-enter). Note that there is a Pascal bias in this database because I am biased towards Pascal, but there is no reason some bright spark couldn’t produce a C equivalent database. You can also look up traps, errors, globals by searching for:
trapA000 - four digit hex number, starting with A
err-108 - decimal number, starting with a minus for OSErrs
err25 - decimal number, positive for system errors.
global910 - three digit hex number for global variables. (QuickDraw globals are not included)
C vs Pascal Procedure formats in the Force
You can change to the C Parse Procedure by typing “C<option-return>” or use the Pascal Parse Procedure by typing “pascal<option-return>”. This means, for instance, when you hit the Type Procedure button using the Pascal Parse Procedure you will get output of the form:
The Force database is not special in any way (except that it contains the programming information for System 7). You can create other databases and switch between them by typing the name <name> and clicking the change button (furthest to the right) (or typing <option-return>).
International Keyboards
Some keyboards don't have the ` character, which makes it difficult to activate ObiWan. To change the activation key, open up ObiWan in ResEdit, open the OBKY resource and edit the third entry. Hot keys for all the other buttons in ObiWan can be edited in this resource too.
International Dictionaries
ObiWan includes International English translation dictionaries, for translating from English to:
French
German
Italian
Latin
Portuguese
Spanish
These dictionaries come from the Internet Dictionary Project, which is project aimed at providing public domain dictionaries. Cool! (If you find an error or omission please consider correcting it at the IDP Update page: <http://www.june29.com/IDP/IDPupdate.html>.)
ObiWan DCMD - Using ObiWan in MacsBug
The ObiWan distribution comes with a DCMD which lets you use ObiWan in MacsBug. Just put the the file ‘ObiWan DCMD’ MacsBug Preferences folder in the Preferences folder and reboot.
In MacsBug, you can now type "obiwan StandardGetFile" and it will show you the StandardGetFile information and let you page through it. For example:
Click the Select button to select a database, then you can get Stats on the database, sort it, add another (sorted!) database, index the database (but that is done automatically for you anyway), or change the word set characters for the database.
Database Format
An ObiWan database is just a TEXT file with a strict format, plus some resources in the resource fork, including the index (which is recalculated if the file size changes) the word character set. The format of the text file is (by example):
=|
indexword data
general stuff, up to 10 lines, each up to 80 characters, ending with a|
nextindexword more data
more stuff|
verynextindexedword more and more data
finally ending with|
=|
The file should be sorted by the indexword (Master Yoda’s sort sorts by the entire entry so if you want related parts to stay in the same order when the database is sorted, they must be ordered in that way). The sort order is straight ASCII, case insensitive. Yes, I can hear you screaming “No, no, use the language independent sort order that the system defines”, (and yes, I do think that comma should go outside the quote mark irrespective of what the English teachers would have you believe :-) but I wish to be able to distribute a database file that works on all machines without having to be resorted.
Let’s see if I can define a BNF for the database format:
character ::= chr(9) | chr(32)..chr(126) | chr(128)..chr(255)
lines MUST be at most 80 characters, and should fit into the window in Geneva 9.
entries MUST be at most 10 lines.
There is no limit to the file size or number of entries (well, ok, the file size is limited by the file system, but that is not my fault, and the number of entries is obviously limited by the size of the file...)
Note: The file absolutely must start and end with =|<cr>. No trailing blank lines.
Setting the Font in a Database
If you wish to use a different font and font size in a in ObiWan, it is possible to set the Font and Font size for a database using ResEdit. Drop the database on ResEdit and add a STR# resource with ID 1984. The first string is the font name, the second is the size. If the STR# resource doesn’t exist, it defaults to Geneva 9 (as specified in STR# 128 in ObiWan).
How It Works
ObiWan uses the Text Services manager to display the floating window (and thus requires System 7.1), and patches into the jGNEFilter list to receive events.
Later on, it watches key presses and if a match for the popup key appears it opens the display window and accepts key strokes. When you hit return it takes the first eight letters of the word (padding with zeros), and scans through an index to find where in the database that word comes, then it positions itself in the database and scans the entries until it finds a matching one and displays that. The “anywhere” search is done using Boyer-Moore search routine - this is one of the most elegant and simple routines I’ve ever seen, if you ever do any searching code, check this out, it is hardly any more complicated than a brute force search, but takes time *inversely* proportional to the length of the search string!
Entering characters into the front application is done by simply returning key down events (with key codes) in response to null events. Word still gets confused (because it only calls WNE if there is an event waiting), but that is to be expected.
Limitations
ObiWan & Master Yoda require System 7.1 or later.
There is a problem with clicks in ObiWan’s display area sometimes being ignored. This happens because the click is sometimes stolen before it gets to the jGNEFilter. You can fix this by installing Matt Slot's TSM Fix (included).
There is also a problem that key presses go into DA windows instead of ObiWan. I don’t really think this is a major problem, but perhaps others disagree.
If you quit ObiWan (using ProcessWatcher for example), the icon remains greyed out in the Finder. This is a bug in the Finder. This problem has been rectified in MacOS 8.
Registering
This program is Shareware, which means if you use it, you must pay for it. A single user license costs US$10. ObiWan 5.2 is a free upgrade from ObiWan 5.1.
You can pay in one of two ways: on-line registration using a web browser, or off-line registration using the Register program.
On-Line Registration
Our online registration can be found at:
<http://kagi.direct.net/cgi-bin/register1.cgi?PL>
Off-Line Registration
Or, using the Register program, you need to:
1. Get hold of a copy of the Register program: Register comes with the ObiWan distribution. You can also get Register from the following sites:
<ftp://ftp.stairways.com/>
<ftp://mirrors.aol.com/pub/peterlewis/>
<ftp://ftp.amug.org/pub/peterlewis/>
..or there are download links on the following Web page:
<http://www.stairways.com/register/topay.html>
2. Run the Register program and fill out the form: You need to enter your name, email, postal address, and the shareware you wish to pay for. The form accepts many different payment methods such as: US Check, Money Order, Cash (in many different currencies), Visa, Mastercard, American Express, First Virtual, and Invoice (to be given to your accounts payable department).
3. Send it to Kagi Shareware: Then either email the data generated by the registration program or print it and send it via postal mail or fax. Credit card information is encoded by the Register program.
The address to send the completed form is output by Register when you Print or Copy the completed form. The addresses are:
Email: shareware@kagi.com
FAX: +1 510 652 6589
Snail-mail:
Kagi Shareware
1442-A Walnut Street #392-PL
Berkeley, California, 94709-1405
USA
You may distribute this program any way you wish as long as you don’t charge for it (reasonable download costs such as Compu$erve are ok (although who would call Compu$erve’s download costs reasonable?)). You must distribute the package in its entirety. We don’t guarantee any support, but we always answer my Email. If we don’t answer Email it is because your message didn’t get to us, or our reply bounced, so please try again and include a valid Internet address if you can.
You MAY NOT DISTRIBUTE this program on any disk or CD without our explicit permission.
Australians may pay in Australian dollars direct to us if they prefer.
Site Licensing
World-wide license: US$2000
Universities or companies site license: US$500
Curtin University and the University of Western Australia are exempt.
A site license covers usage of ObiWan on an unlimited number of machines within 100 miles of some arbitrary central point which are owned by the licensed organization. (A site license will not be useful unless you intend to run more than 50 copies of ObiWan.)
World Wide licenses remove the 100 mile radius restriction.
Warranty
This program should do what is described in this document. If it doesn’t, you can simply stop using it. If you payed for the product, and within a year find that it doesn’t do what has been described here, then you can notify Stairways Shareware and your money will be refunded and your license cancelled.
Fine Print
Peter Lewis hereby disclaims all warranties relating to this software, whether express or implied, including without limitation any implied warranties of merchantability or fitness for a particular purpose. Peter Lewis will not be liable for any special, incidental, consequential, indirect or similar damages due to loss of data or any other reason, even if Peter Lewis or an agent of his has been advised of the possibility of such damages. In no event shall Peter Lewis be liable for any damages, regardless of the form of the claim. The person using the software bears all risk as to the quality and performance of the software.
US Government
Government End Users: If you are acquiring the Software and fonts
on behalf of any unit or agency of the United States Government, the
following provisions apply. The Government agrees:
(i) if the Software and fonts are supplied to the Department of
Defence (DoD), the Software and fonts are classified as "Commercial
Computer Software" and the Government is acquiring only "restricted rights"
in the Software, its documentation and fonts as that term is defined in
Clause 252.227-7013(c)(1) of the DFARS; and
(ii) if the Software and fonts are supplied to any unit or agency
of the United States Government other than DoD, the Government's rights in
the Software, its documentation and fonts will be as defined in Clause
52.227-19(c)(2) of the FAR or, in the case of NASA, in Clause
18-52.227-86(d) of the NASA Supplement to the FAR.
Acknowledgements
This program, like many of my others, would never have gotten here without the help of my friends. Thanks!
Thanks to Jager, Quinn, and Rhys for their ideas and suggestions for ObiWan in the initial design phase. Thanks you J&Q for the initial parsing of the PInterfacesHelp file and the colour icons. Thanks also to the UCC, Curtin, Todd (have fun at AlphaWest!), Steve, c.s.m.p, plaza, ftp.apple.com, Stephen, and anyone who uses ObiWan! Thanks to Greg and the guys at Metrowerks for including ObiWan and giving me a license to their wonderful compiler. ObiWan is written in Metrowerks Pascal. Special thanks go to those brave souls who risked life and Mac beta testing an unknown program. Thanks to Matt Slot for the TSM Fix extension.
