The basic code for HTML Viewer was written as a weekend project, and then enhanced over a few weeks. The reason that the viewer could be written so quickly is due in large part to the existence of Marco Piovanelli's WASTE text engine, for which I am grateful. This library made it possible to overcome the limitations of the Mac's built-in Text Edit Manager, and also made inline graphics possible.

HTML Viewer implements those portions of HTML that are most widely used. Anything HTML Viewer cannot do is probably something that the average HTML author will not want to do anyway. More details on the limitations of HTML Viewer are given below.

HTML Viewer also implements some simple extensions to HTML (which should be ignored by other browsers) that make it more suitable for distributing on-line documentation. More details on the extensions of HTML Viewer are given below.

Using HTML Viewer

If you launch HTML Viewer without a document, a "Home Page" will be displayed (the term "Home Page" comes from the World Wide Web, which uses HTML documents heavily). The Home Page text is read from one of two places, scanned in this order:

1. the data fork of HTML Viewer (unless Power Mac code is present)
2. the file named default.html in the same folder as HTML Viewer

Navigation Aids

The History List

To remove a bookmark from the History list, hold down the command key while selecting the item from the History menu. Yes, you can change the past ;-)

The Bookmarks List

To remove a bookmark from the Bookmarks list, hold down the command key while selecting the item from the Bookmarks menu.

The Index Menu

Graphics Formats in HTML Viewer

Any time you use <IMG SRC=image.gif>, HTML Viewer will first look for a GIF image named image.gif. If this file cannot be found, then HTML Viewer will look for a PNG image named image.png and use it if it is present. This way, an HTML document can refer to and use GIF images on the Web, and the same document can use PNG images with HTML Viewer. Of course, you can also use <IMG SRC=image.png>, in which case only the PNG image will be used and other HTML browsers will not display the graphic unless they support PNG.

Start using PNG now! Help make it as ubiquitous as GIF is, and soon all graphics-aware programs will support it. PNG has some features that make it more flexible than GIF, and PNG is designed to be completely royalty free. I know of one Macintosh graphics utility program -- GraphicConverter by Thorsten Lemke -- that can work with PNG images. GraphicConverter 2.1.4 is the first version that supports PNG. You can download this shareware program ($30) from most of the Macintosh FTP archives.

Forms, CGI applications, and AppleScript & Frontier

In the case of WebSTAR and MacHTTP (the two most popular Macintosh based HTTP servers), form input is passed to an external application by means of an 'sdoc' AppleEvent. Although these Mac CGI programs can be written in any language, the easiest way to write CGIs is to use a scripting language like AppleScript or Frontier. I won't go into the details of writing CGIs, since there are many tutorials and primers available on the Web (search for "WebStar" and "CGI" using your favorite search engine).

HTML Viewer implements both sides of the Forms process: On the browser side, the form is displayed and can accept input, while on the "server" side, HTML Viewer knows how to load and communicate with any CGI program that accepts the 'sdoc' AppleEvent. This makes HTML Viewer a great way to test your Forms and CGIs without having to set up an HTTP server.

If you use AppleScript to write CGIs, HTML Viewer can speed up your development cycle by eliminating the "compile" step. Usually, when you are developing an AppleScript CGI, you cycle through the following steps:

1. Write code
2. Compile script as a runnable "applet"
3. Load form and test CGI script
4. Quit from compiled script applet
5. Fix bugs and cycle

Frontier has a faster development cycle than AppleScript, but HTML Viewer can still speed up CGI development since you don't need to copy your scripts to your HTTP server for testing.

Most of the standard Forms-related markups are recognized by HTML Viewer. The following <INPUT...> types are supported: TEXT, RADIO, CHECKBOX, SUBMIT, RESET, IMAGE, PASSWORD (password is not obscured), HIDDEN, SCRIBBLE, and RANGE (in the last two cases, input is via a text box, and no verification is performed). The FILE input type is not supported. The TEXTAREA and SELECT (and OPTION) markups are also supported within forms, and of course the FORM markup is supported. You can use either the POST or the GET method for submitting a form.

Currently, some of the parameters of the 'sdoc' AppleEvent are filled in with default values. The full request (Kfrq) parameter will always be empty. Input data (direct object and post parameters) is encoded using the standard URL scheme, including space substitution (ASCII 32 is replaced with '+').

Other Features

• Force the current document to be re-read by typing command-R
• Open a document in a new window by holding down the option key
• when clicking a hypertext link
• when opening a new document via the Open command
• when choosing a document from the History menu
• when choosing a reference from the Bookmark menu
• Click and hold on a hypertext link to see its destination
• Single and double quotes are "smart" (except in preformatted text)
• "Smart printing" eliminates widows, orphans, etc.
• Supports GetURL AppleEvent, as well as standard suite
• Uses Internet Config to launch network programs

Color images are dithered using System 7's dithering algorithm, which produces pretty good images most of the time. The good news is that the images retain their colors when moved between monitors on a multiple monitor setup, and when placed on the clipboard. The bad news is that they take slightly longer to draw than when HTML Viewer used its own dithering algorithm. Check out the image below on a black and white monitor to see what happens to a ramp of 16 grays:

Images deeper than 8 bits will always be dithered to 8 bits so that you can Copy and Paste them and they will still work on Macs that do not have 32-bit QuickDraw. I'll probably take this limitation out at some point. For now, this only effects JPEG image quality.

The System 7 dithering algorithm is much better than HTML Viewer's old scheme, which dithered images while they were being loaded and not every time they were drawn.

Limitations

HTML Viewer attempts to understand the most common working vocabulary of HTML, and no more. The three most important features of HTML that are not understood by HTML Viewer are the FIG, MATH, and TABLE related markups. Also missing are many of the attributes that can be added to certain markups. HTML Viewer does not currently support paragraphs (<P>) within list items due to limitations of the text engine.

Most HTML attributes are not supported. The main exceptions to this rule are the HREF, NAME, SRC, and ALIGN attributes, which are necessary in order to locate and navigate files (well, the ALIGN attribute is just for looks). The HREF and NAME attribute are only recognized in the <A...> markup (as is the ISIXextension attribute). The SRC and ALIGN attributes are only recognized in the <IMG...> markup.

Furthermore, HTML Viewer will currently only handle one attribute per markup. This means that you cannot do something like this:

        ...<A HREF=foo NAME=bar> Foobar </A>...

        ...<A HREF=foo> <A NAME=bar> Foobar </A> </A>...

If you come across any other glaring omissions or strange behaviour in HTML Viewer, please let me know.

Extensions

None-the-less, I have decided to include a few simple extensions in HTML Viewer so that it would be more useful for distributing on-line documentation. These extensions will be ignored by other browsers.

The INDEX Markup

        ...<A NAME = "Licensing" ISIX> Licensing Restrictions </A>...

There might be a better (or official) way to do this in HTML. If you know this for sure, let me know and I'll do it right. This is the second method that I've used for the index extension. The first method is still supported, but had some side effects that this new method does not have.

PICT Images

        ...<IMG SRC = "my_graphic.pict">...

The NOTE Markup

The HTML documentation that I've read is unclear about whether ROLE or CLASS is the proper way to specify which standard icon you want to use, so I allow both attributes. ROLE always takes precedence if you have both attributes in NOTE a markup. This might be desirable, because the CLASS attribute is used by OO HTML to "subclass" markup elements.

You can have multi-line notes, and the text will be indented by one tab while the note icon remains aligned to the left margin.

Notes can also have multiple paragraphs. To create multiple paragraphs, use the <P> and </P> markups. Be careful with this option, as the result can sometimes be confusing. It might appear like are multiple notes with the icons missing on all but the first one (this example is a case in point).

If the standard icons just don't do it for you, you can always use your own graphic. For best results, the graphic should be less than 32 pixels wide. To specify a custom graphic, simply use something like the following:

        ...<NOTE SRC="my_icon.png"> this is a note </NOTE>...

One way to get notes to appear reasonably well in other browsers is to use the paragraph markups (<P> and </P>) to surround each paragraph (even if there is only one) in each note. This syntax is neither required nor prohibited by HTML.

The FOOTNOTE Markup

Clicking on a hypertext link that refers to a footnote will display the text of the footnote in a popup window. The window will be resized to fit the footnote text, and can be dismissed by clicking in the window. The text of a footnote will not appear in the main text of the document.

Take a look at the source HTML for this document to see one way you can make footnotes "backward compatible" with older browsers. The markups that make the older browsers do the right thing are ignored by HTML Viewer in the context of a footnote.

The DINGBAT Attribute

• DINGBAT=AUDIO or DINGBAT=SOUND
• DINGBAT=FILE
• DINGBAT=FOLDER
• DINGBAT=PROGRAM (non-standard)
• DINGBAT=APPLE (non-standard)
• DINGBAT=NOTE
• DINGBAT=CAUTION
• DINGBAT=WARNING

Revision History

1.2.2 (3/17/96)
• Added support for Frontier CGIs (or, more accurately, FCGIs)

1.2.1 (3/12/96)
• Added Preferences dialog (blech) for customizing fonts, colors, etc.
• Better support for PNG (support small palettes, grayscale; fixed paeth filter)
• Scrollbar thumb stays synched when text is auto-scrolled during drag-selection
• Fixed crash when an IMG SRC does not refer to a local file
• Saving files places style information where SimpleText can find it
• Added more entity names from the ISO Latin-1 character set (ISO8859-1)
• Supports <FONT> markup, with SIZE and COLOR attributes
• Color contrast check helps prevent "invisible" text
• Fixed "browse ... showing" script command

1.2 (1/31/96)
• Supports <FORM> markup and CGIs (WebSTAR/MacHTTP style)
• Supports sounds (standard Mac formats as well as .au and .wav)
• Supports graphics files as the destination of a link (<A HREF=...>)
• Uses Internet Config to launch Internet tools for network URLs
• Displays DOS and UNIX source files and <PRE> text properly
• Supports BGCOLOR, TEXT, LINK, and VLINK attributes in <BODY> markup
• Supports transparent GIF images, although it could to a better job
• No longer calls InitCursor() when in the background

Previous Versions

1.1.2 (1/19/96 -- AWS Training CD release)
• Proper hit-testing behaviour for images that are also links
• Message displayed when trying to link to a network-based resource
• Links to the (very) top of a page work properly now.

1.1.1 (10/23/95)
• Saved search results now always get the proper icon (creator/type)
• Data fork (PPC code fragment) can be removed, blank window isn't displayed
• Added icons for PiNG, GIFf, and JPEG files
• Select All works for large documents
• Search strings specified by Enter Selection command now work properly

1.1 (10/18/95)
• Multi-file batch find, results can be saved
• Scriptable and recordable (doesn't do much more than open documents)
• Improved image handling, HEIGHT, WIDTH, and BORDER supported in IMG markups
• Improved URL handling, tolerates special characters "/", "%", "#", and ":"

1.0.9.2 (10/12/95 -- not released)
• Uses WASTE 1.2a1
• Fixed crash when some markups had extraneous quotation marks

1.0.9.1 (9/11/95 -- KeyServer Package 4.1J release)
• Supports standard "Get URL" Apple Event (for HTML documents only)
• Properly handles ANSI Standard Latin1 character codes (&#nnn;)
• Fixed Find command for large documents
• Fixed crash when a long, invalid markup tag is encountered

1.0.9 (9/4/95)
• Fixed some serious printing bugs -- basically, printing was broken
• Honor hard page break (^L) characters when printing
• Dash conversion works better, no conversion in <PRE>...</PRE>
• More tolerant of <HR> inside of paragraphs (<P>...</P>)
• Put a throttle on scrolling -- initial scroll will be slowed down

1.0.8 (8/1/95)
• Fixed crash on System 6 MultiFinder (reverted to official MPW link libraries)
• About box uses version from 'vers' resource (BFD).

1.0.7 (7/1/95 -- KeyServer Package 4.1 release)
• Document windows expanded to full screen height when first opened
• "About HTML Viewer..." linked to viewer.html document

1.0.6 (7/1/95)
• Supports JPEG images when QuickTime (Compression Manager) is installed
• System 7 dithering is used instead of internal dithering algorithm
• Supports <NOTE> markup, with optional SRC or DINGBAT attributes
• Supports <FOOTNOTE> markup, which shows a popup footnote window
• Supports DINGBAT attribute in notes and unordered lists
• Each instance of two consecutive dashes (-) is converted to an em-dash (--)
• Comments work to spec (can contain markups, which will also be commented out)
• More tolerant of extraneous <P> markups -- empty paragraphs are ignored
• Fixed hyperlink hotspot calculation when the hyperlink is just an image
• Fixed vertical image alignment (I broke it in version 1.0.5)
• Fixed opening History/Bookmark when second letter of target file is "."

1.0.5 (6/28/95)
• Support for non-interlaced PNG (Portable Network Graphics) images
• Runs native on Power Macintosh (just because it's there)
• HTML Parsing code optimized for greater throughput (it's faster)
• Following a link to an open document does not reload the document
• ISIX name markups can have "/" characters in them and will appear OK
• Nesting the same style works (most important for <BIGGER> and <SMALLER>)

1.0.4 (5/29/95)
• "Smart Printing" avoids widows, orphans, trailing headers, leading whitespace
• Long URLs truncated in the middle when displayed while mouse button down
• Fixed a parsing bug -- escape character after header displayed incorrectly

1.0.3 (5/24/95)
• Handles GIF images better
• Image-dithering added (although very limited)
• Printed text fits full page width (it's a bit faster, too)
• Windows can be resized horizontally (press option while resizing)

1.0.2 (4/26/95)
• Better compatibility with unexpected HTML constructs (pretty vague, huh)
• Plain text (non-HTML) documents retain their entire contents
• CITE and CODE styles work now, BIG and SMALL styles added
• Diacritical marks should be correct now (thanks to all Quebecois users)
• Changed some styling to behave more like other browsers
• Definition Lists no longer add vertical whitespace
• Images do not appear in headers when they shouldn't
• Opening multiple documents (via drag & drop) works now
• Menu items are dimmed as necessary
• Added "View Source" command to File menu
• Saved text uses TeachText as default creator
• Command-selecting a History item removes it

1.0.1 (4/22/95)
• Crash when Drag Manager is not present and user attempts a drag
• Index extension changed from INDEX markup to ISIX attribute
• Whitespace stripped from ends of hypertext link selection

1.0 (4/17/95)
• First release

How to Contact the Authors

Licensing

Copyright. HTML Viewer (the "Software") and any accompanying documentation or written materials (the "Documentation") is copyrighted. You may make copies of the Software and Documentation, provided that you include the Sassafras copyright notice on all copies. Other duplication of the Software or the Documentation is strictly prohibited under the United States copyright laws and international treaties.

Limited warranty and disclaimer of liability. Sassafras makes no warranties, either express or implied, with respect to the Software or included written materials, its quality, performance, merchantability, or fitness for any particular purpose. The Software and written materials are provided "as is" without warranty of any kind. We cannot guarantee you uninterrupted service or the correction of any errors. The entire risk as to the results and performance of the Software is assumed by you. In no event will Sassafras, or anyone else who has been involved with the creation, production or delivery of this product, be liable for direct, indirect, incidental, or consequential damages arising out of the use of, or inability to use the product even if Sassafras has been advised of the possibility of such damages. Because some states do not allow the exclusion or limitation of liability for consequential or incidental damages, the above limitation may not apply to you. Our liability for any damage to you or any party in the event that any of the above limitations are held unenforceable shall not exceed the license fee you paid, regardless of the form of any claim.

Sassafras and the Sassafras logo are registered trademarks of Sassafras Software Inc.

HTML Viewer õ 1995-1996 Sassafras Software Inc.

WASTE text engine õ 1993-1996 Marco Piovanelli

The Graphics Interchange Format õ is the Copyright property of CompuServe Incorporated. GIF(sm) is a Service Mark property of CompuServe Incorporated.

All other product or brand names mentioned in this documentation are trademarks or registered trademarks of their respective companies.