Setup, Issues

There are many different ways to use Newt's Cape:. Two common scenarios are book creation (especially for 1.x) and web browsing (only for 2.x using NIE).

A simplified description of what Newt's Cape does:

  1. it obtains a document (HTML source or other file) from somewhere (Notes, Newtworks, serial connection, web via NIE, etc.)
  2. it parses the HTML source and creates a temporary Newton book
  3. if you have NewtPack installed, you can save the book as a package which appears in Extras;
  4. if you process a different document or quit Newt's Cape, the temporary book is discarded

Book creation scenario

  1. install Newt's Cape
  2. install Sloup to transfer graphics, or documents in advance; or soups (from forms) later
  3. install NewtPack (if available) to save a book as a package
  4. convert any graphics using Newt's Cape Graphic Converter (or ResEdit)
  5. transfer any graphics (using Sloup)
  6. create/obtain HTML documents
  7. start Newt's Cape
  8. access HTML documents via Notepad, NewtWorks, Inbox, Paperback (or try About box sample)
  9. view; navigate; save
  10. transfer other documents
  11. upload books to desktop (ExtractPackage for 1.x; Package Buddy for 2.x) for backup or distribution

Web browsing scenario

  1. NOS 2.x MP130, MP2K or eMate (Newt's Cape will work on MP120, but due to limited heap, "your mileage may vary")
  2. if you are using a PCMCIA card modem, make sure you have at least 180K internal memory free for Newt's Cape (and more for caches)
  3. install any recent system patches system patches
  4. install Newton Internet Enabler(NIE); Newton Internet Enabler (NIE); also an NIE test ("developer goodies") application, e.g., Thumb or NetTest
  5. configure your Modem and Internet Setup; read the documentation
  6. in Preferences for Internet Setup (under "i" button), change "Hang Up" to longer than "Immediately" -- otherwise, NIE may logout immediately after you run each application
  7. test NIE configuration with Thumb, NetTest or other NIE app
  8. install Newt's Cape
  9. install Encoding plugin if you want to convert web pages with other page encodings, e.g., Japanese, Chinese
  10. install JPEG plugin if you want to transfer and convert JPEG graphics
  11. use i:General:Reset All if you had an earlier version of Newt's Cape; check i:General preferences. You should probably specify non-zero cache sizes for HTML and Images; leave off autoLoad (Images) initially; specify a Doc Done Sound.
  12. enter a URL into text area: copy&drag from elsewhere, or use a keyboard, or select a Bookmark:Newt's Cape Example Page, which illustrates various Newt's Cape capabilities. tap top triangle for taller URL field
  13. tap bottom triangle to display status and error information.
  14. tap Newt's Cape icon to open URL
  15. If not already logged in, NIE Connect dialog appears; check/fix phone#. Tap Connect
  16. communication and parsing status information should appear. Finally, book should open and update.
  17. If you transferred a Newton package (.pkg) with the correct MIME type, you have the option to cancel, install the package immediately or later from the Inbox
  18. before tapping on a link or getting another URL, make sure that the current document is finished (you should see some cleanup information appear). You may want to set Doc Done General option to remind you. You may wish to Add Bookmark at end to save URL.
  19. to see embedded graphics, use View:Load with Images
  20. If you encounter problems, be sure to look through other sections of this documentation (use the index), including plans since we may already be aware of the problem. Here are a few common problems:
    modem didn't answer
    make sure your phone line is plugged in
    connect error
    server is busy/isn't available; try again, or try a different site
    VBO problem. did you install the latest system patches?
    strange/hung state
    try Reset HTTP button (under General); or reboot

Creating Documents

HTML text

To create HTML documents, use a text editor or HTML authoring tool, or download web pages from the internet. To minimize problems with Newt's Cape, we would highly recommend that you check any HTML documents first in a desktop web browser before transferring to the Newton. Also, read our suggestions for naming and organizing a collection of interrelated files.

You can enter/edit short documents directly in Notepad, manually or via Serg Koren's HnewTML or Adam Tow's nHTML; create lists with HTMList. You can also create HTML documents in NewtWorks (on NOS 2.1 MessagePads) .

Many new desktop HTML authoring tools are becoming available: Adobe's PageMill, Microsoft's FrontPage, etc. We would be interested in your experience with how the HTML from your authoring tool works with Newt's Cape.


Create your graphics using a standard graphics packages. Generally, keep graphics small; use black&white if you are creating 1.x compatible books or are concerned about storage space. On NOS 2.1 (MP2K and eMate), 4-16 levels of gray are available.

Newton-friendly pages

Although in principle, Newt's Cape should be able to handle most HTML, here are some suggestions for best results.

Transferring Documents/Files

HTML text


This is automatic. Files have a text/html MIME type, and may have .htm or .html extension.


You can access Inbox entries, i.e., beamed from another user, or emailed, e.g., web pages from the WebMail service, for non-real-time web browsing; or, enter/edit short documents directly in Notepad.


use a desktop terminal emulator like ZTerm on the Macintosh or Terminal on Windows to transfer documents directly to Newt's Cape. You need Sloup (2.1 or greater) installed to provide desktop serial or ADSP communication. You can also transfer short documents to Notes (via Sloup), Current limit (due to heap space) is usually ~15K for non-MP130. See Size Constraints. If you would like to transfer one or more documents to the cache (2.x only), turn on desktop? HTML cache option, select Process:Cache Only if you don't want to parse/display document immediately, make sure document contains a BASE http: URL and ends with </HTML> and a final line end. After sending document, Newt's Cape disconnects. Connect to send another. To see document, change to Process:Display Page, select document via File:Open HTML Cache.

For 2.x, you can send other text files, e.g.,

Content-Type: text/plain
Content-Length: 18

this is some text

If there is no Content-Type, it defaults to text/html; length is implicit (when </HTML> is encountered); base URL defaults to <BASE HREF=... inside the document. If there is a Content-Type, it must correspond to an existing helper app; there must also be a Content-Length (length of the content itself, including cr and/or lf chars); Content-Base is optional (and provides a URL or filename that the helperApp might use). Blank line separates header from content.

ADSP (Appletalk)
you can also use ADSP with a few Mac comm programs
If you have a relatively large, static HTML document, you can convert it to Paperback format, download the package, and access the source text via the Open Paperback command



Specify a direct URL for a .gif file, or use Load with Images for a document that should contain graphics, animated GIFs. Graphics are converted and cached, then displayed as/within documents.

Macintosh, Windows

Use Newt's Cape Graphic Converter (NCGC) (available to registered users) on Macintosh or Windows to convert GIF, PICT, BMP files to a text PICT format for Sloup. (Or, the more fearless can copy ICON and PICT resources as hex text via ResEdit). Then, use Sloup, a serial or ADSP connection, and a desktop terminal emulator to transfer the graphics into resource soups on the Newton. Your HTML document can access a graphic with a URL of the form: "soupName/graphicName".


You can also use (animated) graphics that are in the Newton ROM, e.g., Inbox icon and rotating arrows.



You can convert and play several internet sound formats using several helperApp plugins and 3rd party applications, for example: .mod with ModSaver, .wav,.aiff,.au with AudInbox.


Currently, the less technically challenged can copy SND resources as hex text via ResEdit. Then, use Sloup, to transfer the sounds into resource soups on the Newton. Like graphics, your HTML document can access a sound with a URL of the form: "soupName/soundName".


You can also use sounds that are in the Newton ROM, e.g., beep.



You can download a package to the Newton if the URL ends with .pkg, and its MIME type matches current (evolving) package conventions -- preferably "application/x-newton-compatible-pkg"; however, several other types will work (if not, you can customize via helppkgi.htm example). Generally, .pkg should be just a binary file; however, if it is MacBinary (with extra header bytes), hopefully Newt's Cape will fix/ignore this. After downloading, you can confirm if you want to replace and/or install it immediately, or add to Inbox (default store) for later. The prompt displays new (& old) version number and creation date.

Macintosh, Windows

use your favorite package installer
Uploading 1.x
use Newton Connection Kit, and an Extract Package utility
Uploading 2.x
use Package Buddy, Newton Package Uploader, or X-Port

compressed (.sit, .zip) files

Normally, you would uncompress Stuffit(.sit) and Zip(.zip) files on your desktop system. utility URLs, troubleshooting .pkg problems.

Currently, there are no Newton-based tools for decompressing .sit or .zip files. However, there is a web site that you can try (the process is described for Pilot DOC files, but should work for .pkg also).

Size Constraints

Although there are no size limits imposed by HTML, even in desktop web browsers, it usually practical and preferable to have information segmented into "pages" so that a user can look at useful content and context without having to wait a long time.

From a user access/navigation perspective, neither very l-o-n-g files nor single paragraphs are desirable as documents.

On the Newton, it is possible to create very large books from a single HTML file on 2.x (or, if you do not need to display it immediately via Process:Save Package). Still, heap is a major limitation on most Newtons. A practical limit to build and browse a single HTML source in Newt's Cape 2.0 is ~15-20K of text on 1.x -- somewhat larger on 2.x, or if you don't want to save it as a package, and text has minimal markup.

You can use LINK to combine multiple Notes and/or saved books ("chapters"). If you want to have many smaller books (one per HTML document) on NOS 1.x, you will definitely need some kind of Extras/archive manager like NewtCase or ScrollEx.

Current records for largest Newt's Cape books:

Although Newt's Cape wraps wide headings, splits long paragraphs, and scales tables, you may want to shorten and segment individual text items yourself to improve readability if you are creating HTML documents primarily for a smaller (Newton) screen. Somewhat smaller objects are also advantageous from the processing perspective: a lengthy, multi-page P or PRE object might exhaust Newton heap. (At the other extreme, many one-line objects can also rapidly deplete heap due to object overhead).

Since Newt's Cape currently uses Newton books as a container for HTML documents, in order to reference (link to) other books on the Newton using a unique ISBN, you are limited to 14 characters. To maximize portability of HTML documents to other systems and browsers, we suggest using an 8.3 filename, e.g., testdoc1.htm, either all lowercase or all UPPERCASE for consistency. (If you don't care about DOS, then 9.4 is fine).

The current Newton does not have a mechanism such as file directories for organizing packages (actually, you could move books to different folders in Extras), so there is only minor support for "pathnames" currently. BASE is used to interpret relative pathnames for links. For graphics objects, use one level of "directory" to refer to a soup (local objectbase), with the "filename" referring to an object stored in a name slot within the soup. Of course, external http: URL references can be fully specified.

Web Organization

If you are attempting to create a collection of books on the Newton, you should adopt a few simple conventions for creating a collection of interrelated documents and graphics files that will work on both the desktop and Newton. (This section can be skipped if you are web browsing and not saving books for later offline use).

For example, this series of documents resides in the same directory on a desktop computer. You can access documents in subdirectories, but since Newt's Cape ignores directory paths for saved books, the filenames should be unique.

Any graphics are stored as .gif in a subdirectory; in the same directory are Sloup files -- the soup (on the first line), e.g., picts corresponds to the name of the subdirectory, and the name for the PICT object, e.g., foo.gif corresponds to the name of the original file. You can use any directories/soups that you choose, but by convention, we typically put bitmap objects in "bitmaps" and PICTs in the "picts" soup. As mentioned earlier, keeping filenames short (8.3) increases cross-platform portability. Advanced NewtonScript techniques for shadowing URLs

For More Info

This document (in all its formats) is © 1995-2007. Steve Weyer, Greg Simon. All Rights Reserved Worldwide

Version 2.1. Last updated: Sep 2001