Make your own free website on Tripod.com
HTML Viewer is a simple hypertext viewer, or "browser", meant to be used by people who do not have access to a full-featured browser like Mosaic or Netscape. It is also handy for authoring HTML documents, as it does not have the overhead that the more capable browsers have.

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

"You are about to use one of the most powerful, yet easy to use software programs ever written." I've actually seen this statement on another software package (which will remain nameless). Well, HTML Viewer is not that powerful, but it is pretty easy to use. Just drag and drop any text document onto the HTML Viewer icon. If the text document contains any HTML markups, they will be interpreted (within the stated limitations). If the document is plain text, that's how it will appear. You can also use the Open command from the file menu to open any text document.

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
If neither of these locations contains any text, then a blank window is displayed. An HTML document can then be opened using drag and drop or the Open command.

Navigation Aids

HTML Viewer maintains two lists of documents. Documents in these lists can be opened at any time by choosing from the appropriate menu.
The History List
This list contains the twenty most recent documents that have been opened. It is maintained by HTML Viewer (i.e., you cannot change the contents except by opening a new document). This list is persistent over multiple launches of HTML Viewer.

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
This is HTML Viewer's user-configurable document list. Bookmarks can be added to this list in one of two ways. First, you can select some text in a document and then choose the "Add Bookmark" command. You will be prompted for a bookmark label, which will appear in the Bookmarks menu. You can also add any hypertext link to the Bookmarks list by holding down the command key and clicking the link. Note that in this case the link will not be followed.

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

The Index Menu
Some documents will provide an Index to their contents. In such cases, the Index menu appears, and when an item is chosen from it, HTML Viewer will scroll to the proper location in the document. This feature is provided by a simple extension to HTML, and will not be available in other browsers.

Graphics Formats in HTML Viewer

In order to make distribution easier, HTML Viewer supports the Portable Network Graphics (PNG) specification, which is a replacement format for the patented Graphics Interchange Format (GIF). Since PNG is not yet supported by many Mac Web browsers, HTML Viewer provides a way to make your HTML documents "back off" to PNG images.

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

HTML Forms allow users to do more than just passively browse through a set of documents. Forms accept input from the user, and can act on this information in virtually any way. While information input is handled by the HTML browser, the actions taken on this information are handled by a separate program. For HTML forms that are served up by an HTTP server, it is the server that runs a Common Gateway Interface (CGI) program that determines what actions to take.

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
HTML Viewer knows how to load, compile, and execute AppleScript scripts that are in source format (uncompiled), and thus eliminates steps (2) and (4) above. Of course, you can still use the compiled applet with HTML Viewer and you can also use compiled scripts. Note that this is all possible because Apple's Open Scripting Architecture is so damn cool.

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

HTML Viewer has a few "hidden" features that might prove useful to some people. Besides these, HTML Viewer also supports Macintosh Drag and Drop from its windows. This is really a feature of WASTE. I've extended this functionality so that PNG, GIF, and JPEG images can be dragged to other programs that support Drag and Drop, and will be translated to standard Mac PICTs. This means you can also make "clipping" files of any image if you are running a proper version of Finder.

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 (HyperText Markup Language) is a powerful publishing tool that can be used to create technical and non-technical documents in a variety of fields. However, like any complex language, only a small subset of the language, a "working vocabulary", will be used by most people. This is especially true for those who use HTML to create World Wide Web pages.

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>...
You can easily get around this limitation by using the following construct:
        ...<A HREF=foo> <A NAME=bar> Foobar </A> </A>...
HTML Viewer is forgiving of missing <P> and/or </P> markups, although the rules for whitespace will not be overridden. This is about the extent of HTML Viewer's flexibility. If you are creating an HTML document, you should make every effort to write "good" HTML. Using HTML Viewer to check the layout of your work will be a good test whether or not you have succeeded. I still don't know if this is a feature or a flaw, but it is staying the way it is. Think of HTML Viewer as the lint of HTML ;-)

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

Extensions

Extensions are typically only interesting to HTML authors, as they are not available except through the use of HTML. There are many good reasons why HTML browsers should not define any extensions and instead rely on the standard HTML as currently defined. There are even more reasons why HTML authors should not use any browser-specific extensions, but the main one is that the person who reads the document might not be using that particular browser.

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
The more useful extension is the ISIX attribute. When this attribute appears in a name markup (<A NAME), HTML Viewer will place an item in the Index menu. For example:
        ...<A NAME = "Licensing" ISIX> Licensing Restrictions </A>...
This markup places an item named "Licensing" in the Index menu. When the user chooses that item, HTML Viewer will scroll to and select the enclosed text (in this case, "Licensing Restrictions"). Note that the value of the NAME attribute is used for the menu item.

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
The second extension is most useful when writing HTML documents. If you have a graphic in PICT format and don't want to take the time (yet) to convert it to PNG, GIF, or JPEG format, then you can still view it in HTML Viewer. To do so, you must rename the file with the ".pict" extension, as HTML Viewer determines the type of a graphic file using its extension. You then use the standard method for including an inline image:
        ...<IMG SRC = "my_graphic.pict">...
Since other browsers do not support PICT files, you should convert any of these images to PNG, GIF, or JPEG format before distributing your HTML document.
The NOTE Markup
The HTML 3.0 <NOTE> markup is also supported. This isn't really an extension specific to HTML Viewer, but the popular browsers do not yet support it, nor do they really ignore it the way you would want them to. You can use one of three standard note icons, or customize the note with your own graphic. Here are the standard icons:
A simple note (default, ROLE=SIMPLE, ROLE=NOTEA cautionary note (ROLE=CAUTIONA warning note (ROLE=WARNING

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>...
You can use the ALIGN attribute when you use a custom graphic, but not when you use one of the standard icons. However, the alignment is done on the first line, not for the whole note as you might expect. Stick with ALIGN=BASELINE and ALIGN=BOTTOM and you won't be surprised by the outcome.

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
Another HTML 3.0 markup that HTML Viewer supports is <FOOTNOTE>, the footnote markup. Footnotes are most useful for simple term definitions and explanations where definition lists are too formal and where linking to another location in the document would break the flow of the text. Like the <NOTE> markup, other browsers do not yet support footnotes.

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
Just one more feature from HTML 3.0, I promise. The DINGBAT attribute is useful for embedding standard images into your document, and can be used within IMG, NOTE, UL, and LI (within unordered lists) markups. Here's a list of dingbats that are currently available in HTML Viewer: I've looked for a list of standard dingbats, but all I could find were vague references to dingbats mentioning FOLDER and FILE. It seemed fair to include the icons from the NOTE markup. When I find a longer list, HTML Viewer will support more dingbats. Dingbats that are not supported by a certain browser should be replaced by the standard unordered list graphic (typically, this is the bullet character), or by the standard note icon when used in a note.

Revision History

Previous Versions

How to Contact the Authors

Send e-mail on the Internet to kurash@sassafras.com, or on AppleLink to SASSAFRAS. You can send postal mail to:
Sassafras Software Inc.
HTML Viewer Request
P.O. Box 150
Hanover, NH 03755-0150
USA

Licensing

Because HTML Viewer uses the WASTE engine and reads GIF files, and also because it's just plain useful, there is no charge for non-commercial use. This means that you can use HTML Viewer without paying us anything, but if you want to charge for it you will have to get licenses from us (Sassafras Software), Marco Piovanelli (for WASTE), and CompuServe (for GIF).

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.


Mark Valence / Sassafras Software Inc. ( kurash@sassafras.com )


You can use any markup within a footnote, but only non-style text formatting markups will have any effect. Some of the things available in footnotes are:

Markups like these will be ignored: The Footnote window will be resized to fit your footnote, and is dismissed by clicking in the content of the window.

In order to play .au (a common Internet audio file format) and .wav (a common Windows audio file format) you must have QuickTime 2.x and Sound Manager 3.1 installed.

Any version of the Sound Manager should be sufficient to play AIFF audio files.