About Fancy-API2Mac

The application Fancy-API2Mac is a Java software tool for post-processing the HTML files produced by the standard version of the javadoc program from the JavaSoft JDK. Fancy-API2Mac converts these HTML files into a set of HTML files nested into sub-folders, rather than a set of files at one level with very long, and MacOS-hostile, file names.

If you are using Apple's version of javadoc to generate your HTML files, you don't need Fancy-API2Mac. You will find it useful if you receive java-docs from people on other platforms, though. It's also useful in preparing existing sets of API-docs for a platform-neutral release.

The conversion process includes creating the sub-folders, copying HTML into them, and fixing the links throughout the HTML so that the resulting files refer to one another correctly. The converted HTML files are usable on any platform or server, not just Mac OS.

The conversion does not rely on the original file-names in any way, but on the internal structure of each javadoc-generated HTML file. The images sub-folder, if any, is untouched by the conversion, and HTML references to it are unaffected.

The conversion process may fail if you run it on HTML files that have been manually edited after coming out of javadoc. The parser is not terribly robust, and it expects a certain structure. Try not to confuse it.

Table of Contents

Using the Program
Feature Summary
Authorship, Copyright, Legalities, Distribution, etc.
Technical Information, Known Defects, Troubleshooting
Getting Fancy-API2Mac to Work on Other Platforms
Revision and Release History

Revision History Summary

• About Release 1.2
  The license terms have been changed to the open source Artistic License. This permits reuse for commercial purposes, among other things.

  The droplet behavior under Mac OS has been improved somewhat. The console window no longer appears immediately, but only with the first folder dropped or opened. The settings-file no longer has a ".txt" suffix.

  The code remains JDK-1.0.2 compatible, though the enduring utility of this is in question.

• About Release 1.1
  The 1.1 release of Fancy-API2Mac now works well with the HTML generated by PolarDoc, a far better doc-comment extractor than javadoc, in my opinion. I use PolarDoc with a DropMain front-end that I put together.
  • PolarDoc's Home Page
  • DropMain's Home Page

When and When Not to use Fancy-API2Mac

If you receive ZIP or TAR files containing API documentation generated on a non-MacOS platform, e.g. Solaris or W95, and it contains HTML files with names too long for MacOS, you can use Fancy-API2Mac to rename and restructure those files into a MacOS-usable form.

The HTML files resulting from Fancy-API2Mac's conversion are usable on any other platform. That is, the fact that they are MacOS-friendly does not make them hostile to any species of Unix, nor to W95 or NT. You may even find that it is easier to manage and work with the nested HTML files than the conventional "all in one place" structure. You are in luck, because Fancy-API2Mac is itself platform-neutral (and free). See Other Platforms below for more information about using the program on other platforms.

If you use the javadoc from MRJ, you DO NOT need Fancy-API2Mac, and it won't work anyway. MRJ's javadoc already places its output into nested sub-folders, hence does not need post-processing by Fancy-API2Mac. Attempting to convert such a folder with Fancy-API2Mac is a common source of errors and broken HTML files.

Operating Requirements and Features under MacOS

Fancy-API2Mac has been extensively used and tested under MRJ, which is Apple's MacOS Runtime for Java. It works with MRJ 1.5, 1.5.1, or 2.0. It may work on other MRJ versions, but has not been tested there. You must have MRJ installed before running the program. You don't need JBindery or anything from the MRJ SDK.

MRJ itself requires System 7.5.3(?) for MRJ 1.5.*, and System 7.6.1 or later for MRJ 2.0.*.

Fancy-API2Mac is a fully stand-alone double-clickable Java application. It requires nothing other than MRJ itself. Specifically, it does not require MRJ-SDK, nor any Java-language development system in order to run. It does not use the javadoc program in any way, only the HTML files produced by that program. The original HTML files are left in their original location under their original names.

Fancy-API2Mac is drag-n-drop aware (in the MacOS Finder sense, not the Java sense), and will accept folders of HTML files (i.e. API docs from javadoc) dropped onto its Finder icon. This is a MacOS-only feature. The program IS NOT drag-n-drop aware in the Java sense, and does not use any feature of Java that provides the drag-n-drop feature within the language. If Fancy-API2Mac's window doesn't say that you can drop API-folders onto its Finder icon, you can't do it. The program internally detects the possibility of doing drag-n-drop, and adjusts its window display accordingly.

Fancy-API2Mac creates HTML files owned by a browser. You can configure which browser that is using a settings-file, or by altering specific Java properties that the program looks for. Lacking a property-setting and a settings-file, the program defaults to Netscape Navigator as the browser (i.e. creator-ID 'MOSS', file-type 'TEXT').

The program and its settings-file can be located anywhere together. The name of the settings-file must be "API2Mac-settings" in order for the program to look in it.

Since these settings are MacOS-specific, and have no meaning on other platforms, it's safe to remove the settings-file on those platforms. No harm is done, and no error occurs.

Operating Requirements and Features Under Other OS's

Fancy-API2Mac should work under any 1.0.2-compatible or 1.1-compatible JVM. You will have to figure out for yourself what command-line and options to use. See Other Platforms below for the important parameters and options you have to supply.

The most important thing to do is to include the ZIP-files "Fancy-API2Mac.zip" and "MRJToolkitStubs+NatObj.zip" in your class-path. The latter file contains stub-classes for certain MacOS-specific features of the program. If you already use the Apple-supplied stubs, you will still need this ZIP-file, since it contains an interface that is not in the Apple stub-file. Only non-MacOS users need this file, since MRJ contains the needed classes itself.

These are the main differences between Fancy-API2Mac and the original API2Mac program.

Platform-Neutral Improvements

• New in release 1.1 -- Now works better with the output of PolarDoc, a much nicer extractor of doc-comments than javadoc.

• Distributed as a compiled set of ZIP'ed class files that should work on any platform. No compilation necessary (I hope).

• Now works under JDK 1.0.2, to the extent possible (i.e. can't do character-set transliteration). Still compatible with JDK 1.1, too.

• Displays a main program-window with brief instructions and a Convert... button. This is a more informative GUI than just a menu and no window.

• Has a File menu with Convert... and Quit items.

• Allows selecting an output folder-name, rather than being hard-wired to newAPI.

MacOS-Only Features

• Distributed as a complete double-clickable, drag-n-droppable application program. Still includes all source code and other parts needed to rebuild.

• When running under MRJ, drag-n-drop of API origin-folders onto the program's Finder-icon is supported and handled in the program. This is easier than the flimsy "select file within folder" interface that other platforms are stuck with.

• The main program-window is MRJ-sensitive, and only shows the "drag-n-drop" info when it detects that it's running under MRJ.

• The File menu-items have command-keys under MRJ, even under MRJ 1.5.

• The creator-ID and file-type of converted HTML files is configurable. Settings come from "command-line" properties or the file "API2Mac-settings" (read the file itself to see how to do it and the property names). Thus, you can define the properties on the command-line (or equivalent) if you want. The hard-wired defaults are now for the Netscape Navigator browser. Andreas's defaults were for MSIE. Chacun a son gout. :-)

• Has an About... box (dialog) under the Apple-menu. The dialog itself is platform-neutral, but its sole means of appearance is the Apple-menu, which isn't.

• Beeps at you when certain operational errors occur. The beeper code is not cross-platform, but is easy to alter. Even easier if you use JDK 1.1's System.beep() method.

• NON-FEATURE -- Sadly, you can't replace existing folders on MacOS, because the MacOS PutFile dialog doesn't understand the concept of replacing an entire folder, so won't allow it.

Authorship

This program is the work of three different individuals, not associated in any way:

Andreas Pfaller

wrote the original API2Mac program, which had a minimal user-interface, and only wrote its output to a hard-wired folder-name. It did its job well enough that...

Gregory Guerin

had the nutty idea of improving the interface and configurability, so he didn't have to think so hard each time he used it. He is the primary culprit for the Fancy-API2Mac program as a whole, and is the sole author of this HTML document. He started with Andreas's original API2Mac and added the features that made it into this humble program. Some of those features (including the About-box and drag-n-drop interface) were based on work done for a code-fragment call "MRJHelloWorld" written by...

Sven Van Caekenberghe at Ping in Belgium

where he keeps an Unofficial MRJ FAQ page that contains a useful collection of MRJ tips and solutions. There are other useful Java tidbits elsewhere on his site.

Copyrights

The original API2Mac was released under a "no commercial use" license by Andreas Pfaller. The current version is now under the open source Artistic License. There are no other restrictions.

The HTML output files generated by Fancy-API2Mac have no restrictions placed on their use or distribution by the conversion, not even the Artistic License.

Changes to API2Mac

I changed Andreas's original code to work under Java 1.0.2, i.e. MRJ 1.5. This necessitated some minor changes to the original source-file, but the changes are forward-compatible with Java 1.1 and MRJ 2.0. You'll see deprecation warnings when compiled under Java 1.1, however. These are normal.

I also split Andreas's original single-file three-class source into a class-per-file structure, and put them into a package.

Finally, I left the original main() entry-point in place, even though it is hard to work with because it's now in a package. Obviously, I no longer call that entry-point.

Known Operating Defects

• MRJ's GetFile dialog that asks for a "file within a folder to be converted" displays no prompt, which is quite cryptic.

  Work-around -- read the instructions in the main program window first, or use drag-n-drop from the Finder. The lack of a prompt in the dialog is a known defect... er, I mean "unresolved issue".
  Alternative work-around -- install "Navigation Services" if it's not built into your System already. It shows the prompt-string in its selection dialog.

Known Design Flaws

• The primary output-feedback mechanism is still the console window, just like Andreas wrote it. [I didn't want to do THAT much improvement. --GLG] I could probably make a reasonable AWT-interception or replacement for System.out.println(), but that pesky activity called "real work" keeps getting in the way.

• The properties/settings file is only looked for in the application's own folder, not in the Preferences folder. I could have used the "user.home" System-property, which refers to the Preferences folder under MacOS, but I was too lazy. If you want it, add it.

• The "select a file within folder" interface is pretty weak, but Java doesn't have much in the way of alternatives. Ouch. (This is one reason why I like the droplet behavior under Mac OS so much more.)

Troubleshooting and Configuring

Q: The program's icon doesn't highlight when I drag a folder on top of it in the Finder. That is, it's not drag-n-droppable. What's going on?

A: The program's info that tells the Finder it is drag-n-droppable isn't present in the invisible desktop file. Try one or more of the following remedies to get the Finder to update its desktop file:

1. Drag the Fancy-API2Mac program to another hard-drive volume or a floppy disk, remove the original, then copy it back. The program icon should now hilite when a folder is dragged over it.
2. If the program-icon still doesn't hilite for folders dragged over it, restart the computer and see if the Finder will read the new information.
3. If still no hilite, try rebuilding the desktop file at startup (hold down command+option until dialog prompts you about rebuilding the desktop file).
4. If still not, I'm stumped, and you'll have to use the Convert... button or menu-item. Sorry.

Q: I have a type-X file in the API-folder that I told Fancy-API2Mac to convert. It chokes and throws an exception (or crashes) when it comes to that file.

A: Meet the not-very-robust parser and file-scanner. It doesn't like extra files, and it's not smart enough to skip over files that look like they might choke it.

You'll have to move everything out of the API-folder that wasn't put there by javadoc itself.

Q: I drop a folder on Fancy-API2Mac that doesn't have API files in it, and the program complains that "The folder must contain 'packages.html' to be processed."

A: That's a feature, not a bug. To prevent pointless processing of files that don't really contain API files, Fancy-API2Mac looks for packages.html to indicate that the source folder really does contain HTML generated by javadoc, which always writes that file to its output folder.

Q: I think there's a bug in the program. It mangles the API HTML files that I create with javadoc on my Mac. All the links are broken, and most of the output files are missing or misplaced.

A: Don't use Fancy-API2Mac if you ran javadoc on the Mac using MRJ. MRJ's javadoc already puts things into nested folders (although it doesn't set the file-type to a browser... oops).

If you used the javadoc from some other MacOS-based Java development system, their output may not be parseable by API2Mac. Sorry.

Q: I did like you said to run Fancy-API2Mac on W95, and it runs, but the main window initially appears with the lower line of text mostly clipped off. What did I do wrong?

A: There is a bug in the JavaSoft JVM's (and maybe others) under W95 (and maybe NT, I didn't check). When the menu-bar appears in the window, it pushes the content down, but fails to resize the window accordingly. Thus, the bottom 20 pixels or so of window content (text in this case) is pushed beyond the visible window bounds. You can resize the window manually to get the content back.

This bug appears in JDK 1.1.4 on W95 and all prior JDK's that I've seen. It may or may not be fixed in later versions, I haven't checked.

Q: I want to change the file-type of Fancy-API2Mac's HTML files so they automatically launch my browser. How do I do this?

A: Start by finding out what the creator-ID of your browser is. This is a 4-character identifier of some kind. It may contain special Mac-only characters like accented letters or bullets. If it does, you'll have to further discover what the hex representation of the special-characters is. You can search for this on the web, or ask a Mac font-and-type person, or look it up in Inside Macintosh: Text, Chapter 1, page 1-55.

Armed with the creator-ID, edit the file "API2Mac-settings" using any text-editor (even SimpleText will work). Follow the instructions in the file itself, changing the value of the file.owner setting/property. Remember that comment-lines start with '#', and are ignored. Save the file and close it.

If Fancy-API2Mac is already running, you'll have to quit it and launch it again to get it to read the new settings.

Other FAQ's

Q: I'd like to add new-feature-X to Fancy-API2Mac. How do I do that, or can I get you to add it for me?

A: You look at the existing program source, figure out what to change, then write the new software pieces you need. That's why it's distributed as source.

Sorry, but I'm not taking feature-requests for Fancy-API2Mac. It's AS-IS software. Maybe someone you know can add features for you if you're not a Java programmer. That's why it's distributed as source.

-- 1.2 -- 14May99 --

Changed license terms to Artistic License.

Remove ".txt" from settings-file name, since unneeded on Mac OS, and that is the only platform that cares about the setting-values anyway.

Slight restructuring to install event-handlers last, improving droplet behavior.

Don't emit text to console until first conversion.

Replace 'App' class and its main() with app.Application.main().

Use BufferedInputStream reading properties.

Eliminate bug where multiple "About..." dialogs could appear.

-- 1.1.1 -- 01Jun98 --

Fixed the bug that would sometimes incorrectly truncate file-names, putting an '@' character into the truncated name (at least I think it's fixed).

Major rework of how file-names get mapped and translated. Now does a pre-processing pass that adds all names and determines the final file-names of all files. The primary consequence of this is that Fancy-API2Mac now correctly translates the output of PolarDoc when its output-names are constrained to 8.3-type names. A bit surprisingly, this extra pass through the files has very little effect on overall conversion time -- usually none, but in a few cases about 5-10% slower.

Add feature that places PolarDoc's "thumb" index-pages into an A-Z sub-folder. This really cleans up the top level, where AllNames.html, tree.html, etc. are located.

Version 1.1.0 wasn't released.

-- 1.0 -- 15Mar98 --

Rewrote this document in HTML. Duh. Added large amounts of material.

Added "Troubleshooting" section. Double-duh.

Finally did some testing under other platforms, i.e. W95 under Virtual PC... Hmmm, glacial is putting it mildly, but considering it's 3 levels of emulation (PowerPC emulating Pentium emulating JVM) it's amazing it even runs (well, walks).

Observed W95 menu-bar push-off bug (still). Sheesh, saw the same bug in Sun's JDK 1.0.2 over a year ago. Wish I knew the work-around for this, since all my tries were futile.

Fixed latent bug in NameMapper.renameDocFile(). It tests out OK under MRJ and W95 JDK 1.1.4. Enough, already, it's going out.

-- 1.0fc1 -- 10Mar98 --

Drag-n-drop without pre-launching now works. I didn't do anything to address this, it just started working. Rather, when I tried it one day, it was already working.

Revised how AboutDialog is instantiated, so its title is assigned by caller.

Moved registerHandlers() earlier, so they get established as soon as practical.

-- 1.0b4 -- 08Mar98 --

I've improved the I/O since the prior version, so it should be about 20-25% faster, on the whole. At least it is for me. FYI & FWIW, I eliminated the use of DataOutputStream and did my own String-to-bytes conversion.

Added 'vers' resources.

Added 'hfdr' resource for balloon-help in Finder. No balloon-help in program itself. Sorry, folks.

Improved file-type and owner-ID settings-retrieval to accept hex-number format. This is because Mac-specific characters don't work, nor could I get UniCode to work for MRJToolkit. You can read about the feature in "API2Mac-settings".

I fixed a problem in HTMLConverter.processFile() that was presuming the output-folder name was "newAPI". This resulted in much longer status-lines than necessary, but no operating errors. The extra verbosity was annoying, though.

-- no version ID -- 02Mar98 --

Initial beta-quality release. I forgot to put in 'vers' resources. D'oh!

---

To Greg's Home Page
To Greg's Software Page