Reporting Newt's Cape Problems

You might check first if this is a known problem (next section) or if it's something already fixed in a newer version/beta, or mentioned in Plans.

To help me resolve problems with Newt's Cape most quickly, I would appreciate the following information:

error code number; if convenient, include an error trace using Bug Trap (though sometimes this generates bogus errors related to communication -- see details below)
command/actions prior to the error
the version of Newt's Cape you are using
the model MessagePad and OS version
if you were accessing the web, the URL(s); NIE version
anything else I should know about your configuration (extensions, etc.)

Common Questions, Known Newt's Cape Problems, Missing Features

I will be updating this section in near future to be more complete, to reflect common questions/problems, more workarounds and recent reports.

What, exactly, is Newt's Cape? (book reader, browser, NetHopper replacement)?

book reader
Newt's Cape creates Newton books like Newton Press, but it runs on the Newton, with source documents in HTML format (rather than word processing formats). The resulting books use the same built-in Newton book reader, so Newt's Cape is a book creation tool not a reader. Like Bookmaker (which requires NTK), Newt's Cape can include more sophisticated objects than just text and (animated) graphics -- links, (custom) form objects, scripts, etc. to this extent, it's an application development environment (NewtonScript examples). This book creation functionality can be used on any MessagePad (1.x or 2.x), with documents from Notes, NewtWorks (if avail), Inbox, desktop (via serial); you can include images from web (GIF, JPEG), though it's also possible to use graphics from desktop (GIF,PICT,BMP) (after some extra conversion/transfer); images that are too large for screen (or table cell) display 2D scroller. gray scale images are possible on NOS 2.1 Newtons.
browser
yes. HTML documents can also come from the web on 2.x. (you can even get web pages from Inbox on 1.x Newtons, though it requires an email client, setting up a Proxy, and some patience). After Newt's Cape displays the current web page as a (temporary) book, you can just follow a link or bookmark to another page. (or first save the current book as a permanent book package in Extras). Newt's Cape also contains a Scheduling mechanism for batch downloading pages (so could replace 3rd party products like WebXPress).
NetHopper replacement
Newt's Cape is an alternative to NetHopper, and does more (and continues to be supported). Some users like the NetHopper interface/metaphor better (so have both installed), but many users like just Newt's Cape. For an introduction to Newt's Cape from Peter Rand: review of version 1.5; help/intro for 2.0
dessert topping and floor wax
;-)

HotMail doesn't work. though there were some fixes in 2.0s2, unfortunately, www.hotmail.com now uses SSL (https://) for password authentication; and in the course of Microsoft's plugging of "security leaks", the following may not work either: HotMail form on http://home.microsoft.com (thanks to Lee Moon for this tip), or you could create a simple local page (in Notes):

<HTML><HEAD><TITLE>Hotmail</TITLE></HEAD><BODY>

<form name="HotForm" ACTION="http://www.hotmail.com/cgi-bin/start" method="post">
<input type="hidden" name="curmbox" value="ACTIVE">
<input type="hidden" name="js" value="no">

<P>Hotmail Logon Name:
<input type="text" name="login" value="" size="16" maxlength="16">
<P>Hotmail Password:
<input type="password" name="passwd" size="16" maxlength="16">

<INPUT TYPE="submit" VALUE="enter" name="submit1">
</form>
</BODY></HTML>

NIE connection dropped after each page. Really old versions of Newt's Cape (or current versions where you set the i:General:Other Options:Reset HTTP preference) released the connection after getting each page, which then started the NIE countdown (e.g., drop connection after "n minutes" with flashing star at top) -- if so, lengthen the NIE timeout to longer than "immediately". If this isn't the problem, it's quite likely that you don't have the correct modem setup -- check/experiment with your configuration (info).
-16022 error when NIE connects. Extras Drawer:Prefs:Modem and choose the specific PCMCIA card slot (not Default)
after quitting Newt's Cape (or File:Reset HTTP), dialog appears with "Please wait... HTTP FSM is executing toward terminal state." (Go Away). if Newt's Cape's internal state or network connection is confused, this can sometimes appear. If it doesn't go away by itself after a few seconds, tap Go Away to get rid of it. Newt's Cape should be ok the next time you run it; if things still don't work, you might logout your NIE connection (and possibly soft reboot).
Although you might uncover new Newt's Cape errors with BugTrap, it more frequently reports normal "exceptions" that Newt's Cape is expecting and handling. For example, when transferring a text (or binary) file of unknown length (indicated by "?" for length in status area), checking/obtaining final data at end of that file often generates an exception, which is normally hidden, but which BugTrap unfortunately exposes. If you see a report similar to the following, you should either ignore it, or turn off BugTrap (assuming Newt's Cape is behaving normally otherwise):
```
Stack Trace
input() <native function>

eventHandler({eventCode: 2,...
...
Current Receiver
...
SetFindVar 'premDisc
Push       'evt.ex
```
if an uncommented SCRIPT occurs inside a table, its text is displayed (rather than ignored)
NewtWorks warning. NewtWorks, especially large documents, may trigger latent Newton system memory bugs. I'd highly recommend that you do regular backups, and use any newer versions of Newt's Cape and HTMList (with workarounds for Newtworks problems)
Newt's Cape example pages have undefined links or actions. This can happen if you use Newt's Cape-specific pages in a desktop browser, since pages may use NewtonScript (instead of JavaScript) to implement local actions. You also need to set the i:General:NewtonScript preference to Compile -- otherwise Newt's Cape ignores NewtonScript methods/expressions.
I only see "?" for images. If you're loading pages from the web and seeing "?" icons, it's probably because by default, "autoloading" of images is turned off and the lazy authors of those pages did not include an ALT attribute (text label). You can manually load images for a page by using View:Load with Images, which provides an overview of images that you can load selectively. Or, if you always want images to be loaded, you can select i:General:Images:autoload and select a number or All to specify how many images to load automatically for a page. If images are in the cache, they will be displayed regardless of this setting; autoload applies only to new (unloaded) images. If you don't like the "?" icon for missing images, you can provide your own "ALT label" when pages are missing these -- you would set i:General:Other Options:IMG:no ALT to something like "MISSING IMAGE".
how can I surf the web on 1.x Newtons or without NIE? If you can't use NIE (due to dialup like AOL; or older Newtons; or ISP that doesn't support POP/SLIP), you could access the web via email proxy -- though I wouldn't call it "surfing" since it might be minutes/hours before you get back web pages.
1. if you've got email access
2. and have read Newt's Cape email proxy doc
3. you could set i:General:Other Options:Proxy URL to (for example): mailto:webmail@www.ucc.ie?subject=&body=GET ^0 (note: the default "web-mail" service is no longer available -- try another mail proxy server)
4. whenever you request a URL (via status area or by tapping a link), Newt's Cape would generate an email message to the proxy which would look like (in this case):
```
To: webmail@www.ucc.ie
Subject:

GET http://www.foo.com
```
5. after you send these email requests, you would eventually receive some replies that include HTML pages in Inbox.
6. in Newt's Cape, use File:Open Inbox to access the pages
how can I edit books on Newton?
1. You can save HTML to Notes or NewtWorks (File:Save HTML to Notes/NewtWorks)
2. You can generate HTML if HTMList is installed: save an outline or formatted Note as HTML, save a formatted Newtworks doc as HTML, or saving an existing book as HTML in Notes or NewtWorks
3. To edit source on Newton, you could use Notes (if source isn't too long, or you use something like SuperNotePad, or you can combine multiple notes into a single book) or NewtWorks (2.1).
4. There are several editor add-ons (nHTML and HnewTML) to assist with HTML tag creation.
5. Once you've got HTML, process that with Newt's Cape (File:Open Notes or NewtWorks) to create a book.
empty A NAME ranges are ignored currently (not sure when/if this will be fixed, since it involves changes in both the parser and processing modules)
if you had a much older version of Newt's Cape installed, it might be best to do a Reset All to reset preferences to default settings before installing new version
2.x: renaming folders in overview won't work properly (Newt's Cape doesn't receive/recognize the rename event); so, either move items to another folder before renaming, or move items from "All" afterwords
2.x: cache entries become duplicated in some situations -- specific URLs/steps to reproduce this problem are welcome (maybe related to POST data? or HTML URLs that don't end with .htm/.html?)
horizontal gesture does not work on unloaded server image maps (which appear as buttons)
2.x: there appears to be a problem with the NTE Big5 (Chinese) encoding -- contacting author
2.x: Sometimes servers send a document anyway, even if Newt's Cape sends the correct last modified date for cached item (not sure if this is a HTTP/1.0 vs. 1.1 client issue)
2.x: when Cookies:Ask is set, there is a delay (until after confirmation) before cookie is stored; this can be a problem if a site provides a cookie and then redirects -- in this case, you'd probably want to set Cookies preference to Keep, i.e., no prompt.
what is a cookie? Briefly, a cookie is a little "frame" with a few slots and values that the server sends to browser -- somewhat like a "temporary membership card" or slip of paper with things that a server can't remember between transactions. Whenever the browser encounters a URL with the specified host, it sends along the cookie. Presumably the server can use this information to customize what it sends back, though it might just be to help keep track of unique hits, and sometimes it's just to help preserve state information in temporary variables since http is generally a "stateless protocol" (one alternative is that the server would have to send back custom HTML pages that contained hidden INPUT fields that would pass back intermediate results to next stage of a query etc.). if you've provided some personal info via a login page at the site, some of that might be encoded in the cookie, but otherwise, there's nothing sinister about them. (Newt's Cape doesn't send anything from your Newton Owner info, for example). Newt's Cape stores them in current preference set; you can get rid of them (there) by changing pref back to Skip. Sometimes a site will work ok if you ignore cookies; some sites won't work without them. Generally they should come with expiration date so that they'll get recycled eventually.
2.x: certain sites (my.yahoo.com) have a fixed list of browsers known to support cookies, frames, tables; if you'd like to trick sites into thinking Newt's Cape is a more capable browser, you can try adding an Agent Prefix (under i:General:Other Options): Mozilla/2.0 [en] -- this gets added to Newt's Cape's normal "User-Agent" header which identifies the browser to the server. Even so I have not been able to figure out how to make some parts of my.yahoo.com work, e.g., mail.yahoo.com.
For pages with complex (nested) tables, if forms do not appear/work correctly, you may want to turn on "Ignore Tables" (value: any non-empty string) under i:General:Other Options
scrolling long menus in Newt's Cape may conflict with ScrollMenus extension
2.x: I suspect there is a system bug in eMate and MP2K (non-upgraded) related to heap management; sometimes, there can be l-o-n-g delays (or system hang) when just closing an overview, or closing a book or following a link (which often causes the current book to close) -- even when a lot of heap appears to be available. This is exacerbated by having an NIE connection (esp. if NTK Inspector is connected also). I don't know if any workaround is possible, but if anyone can reproduce this behavior consistently and simply, please let me know.
applications managers that freeze an application automatically and immediately after it quits may generate an error for Newt's Cape (and Sloup) due to deferred actions
2.x: one user has reported "truncation" (or disconnect) problems with NIE 2.0 on eMate for Japanese web sites -- the symptom is that the file is not entirely transferred; this problem does not occur with NIE 1.1. I have not been able to reproduce on MP2K with NIE 2.0 (and cannot get a response from Apple); please let me know whether this problem is more widespread/reproducible
1.x: long paragraphs with mixed font styles/sizes may have extra lines after them (Newton's built-in text measurement supports only a single font)
attribute expressions that split across lines sometimes add an extra space to content
embedded null (0) characters can cause premature end of document
versions of NewtPack < 3.4e are incompatible or produce incorrect packages (3.4e available to registered users)
table borders may not line up; table row splitting of mixed height graphics?
does not properly parse "ambiguous" HTML attributes with embedded = unless enclosed in "", e.g., ...href="/foo.cgi?enter=main">
2.x: GIF conversion errors (especially with gray scale) may be due to heap problems; if using 16-grays, try 4-grays. or it could be a store problem (remove some items and try again after a reboot).
when quitting, if you see a "cleaning up FSM" progress box appear for more than a few seconds, you can usually tap "Go Away", though it's possible that the NIE connection was not properly disposed of; it should be ok next time to reopen Newt's Cape.
Go:(Clear History) should probably appear if history list is empty (rather than not at all); since the book bar is now always open by default, following links within same book does not properly update the appearance of Back/Forward buttons in the book bar -- they do update properly if you toggle it close/open, or follow a link to a different document.
Process:Display Item doesn't really work (i.e., refresh after each item); if this isn't really used, I may not fix
2.x: install Encode plugin only if you need it (e.g., for Japanese, Chinese pages), and then make sure you have the latest version (1.0a had a bug) -- this should avoid some errors when Submitting forms (as well save space and time).
no support for Java, Javascript, SSL (secure socket layer), CSS (cascading style sheets), vCard,iCalendar, XML, ...; some work on Java and KVM -- assuming this could be ported, it might require a lot of memory: both storage and heap. Javascript might be doable (if a parser were available to help convert to NewtonScript), mapping to browser/document/object model appears straightforward -- except for certain user events and dynamic changes possible in browsers (but not currently in books).
possible to Put Away vCard/vCalendar data from web or email into Names/Dates? In 1997, Newt's Cape (via a helperApp) could transfer/add vCard and vCalendar entries via http and email. At that time, I was not able to distribute due to pending commercial possibilities; now, I could distribute, but it would require time (that I don't have) to clean up, test, extend and update to latest standards.
HTML docs not visible via File:Open NetHopper cache. Once NetHopper views the HTML from WebXPress, NetHopper discards the source and converts it into its own internal format. Newt's Cape can process the original HTML; it can handle both unconverted or converted GIFs from the NH cache.
how do I access maps? You should be able to use many web-based map sites, though sometimes the appearance and navigation are messy/slow if pages use nested/complex tables or if many images must be transferred. I'd recommend that you try the Newt's Cape makemap example that creates a book via MapBlast with overview linked to more detailed maps.
what does tapping on a mailto: link do? If you tap on a link in a document that contains someone's email address -- these would appear in the HTML source as <A HREF="mailto:somebody@foo.com">John Doe</A> -- Newt's Cape automatically places an email message in your outbox, which you can then edit before sending. If it's just text, you can always just copy the text into the address of your email client.
can I download pages from desktop to read offline via Newt's Cape?
1. If you want relative URLs to work, Newt's Cape needs to know the full URL of the document. your document should include <BASE HREF=... even inside  is ok (or you can add a prefix header with Content-Base: http://)
2. In order to save source in its HTML cache, set Newt's Cape's "desktop?" preference under i:General:HTML
3. Sloup must be installed on Newton to provide serial/ADSP/IrDA connectivity
4. On desktop, open a serial connection using a terminal program like ZTerm or HyperTerminal
5. In Newt's Cape: File:Open Desktop; select matching connection speed.
6. On desktop, Send Text
7. Newt's Cape receives file, then parses and displays it (and optionally caches source).
how transfer and view complete HTML hierarchies (entire websites)? Assuming you wanted all of the links on a page, you could Schedule a page and turn on Autolink? feature (in Newt's Cape 2.0u-2 or later); to omit some of the links, you could add URL fragments (e.g., hosts or file extensions) to AutoLink Exceptions. In older versions of Newt's Cape, you could collect the individual links as bookmarks (horizontal gesture, Add Bookmark), and then Schedule the retrieval as a group. If each file were independent, i.e., didn't contain relative URLs for images or links, you could just batch transfer the desktop files to Notes (if short) or to NewtWorks as is; otherwise, there's not a trivial way to transfer a collection of files from desktop since each would need a BASE URL in order to be cached and used for relative URLs. This can be done in a few different ways, depending on the transfer mechanism:
- if transferred directly to Newt's Cape, it needs either a Content-Base: header field or a BASE tag in the content
- if transferred via Sloup to Notes or NewtWorks, the doc would need a BASE tag in the content.
- if transferred via Sloup directly to HTML Cache, the Sloup header would need URL field set.
To combine multiple HTML files ("chapters") into a single book, there are two mechanisms in Newt's Cape: FRAMEs can merge source of the individual frames into the main FRAMESET document; the LINK mechanism allows you to merge fragments of HTML source (usually from Notes) or other books you've already created -- there's an example (in the reference docs) of using LINK to concatenate individual books into a master book; bookpart.slp.
how can I transfer HTML with images from desktop into Newton? It would be easiest if you could just load the files directly to your Newton from the web (using NIE) -- that way files would be properly converted/cached/integrated already. If that's not possible/feasible, then you can transfer both HTML and (converted) GIFs via serial to the Newton, and have the final document appear and behave correctly. However, this is not a simple or automatic process (and is available only to registered users):
1. get familiar with Sloup (see the Sloup docs and Peter Rand's help book). send a simple text file to Notes to make sure serial communication is configured properly and to become familiar with the basic process of sending a Sloup file.
2. if the HTML file is from somewhere else and you want to keep the original image filenames and modify the original source as little as possible, then probably the best thing to do is to transfer the HTML source directly into Newt's Cape's HTML Cache, and the converted images directly into the Image Cache. Take a look at the following example on your desktop: htmlcach.slp
3. transfer this example via Sloup, and check Newt's Cape's HTML cache to make sure the documents are there
4. or, you can turn on the i:General:HTML:desktop? preference, include a BASE tag in your HTML document (so Newt's Cape knows its URL), then use File:Open Desktop in Newt's Cape, and transfer the document (this uses Sloup underneath).
5. to convert images using NCGC, look at the NCGC documentation. The NCGC description is oriented toward storing graphics in your own graphic soup(database), with simple "relative URLs" in your HTML source, which would be resolved as: <IMG SRC="theSoupName/graphicName"> like bitmaps/myimage1.
6. you can store the graphics directly into Newt's Cape's Image Cache under the original URL, with a minor amount of editing of the .slp file that NCGC generates. You'd change the soupname, entryspec and first line of data (but same bitmap data). For example, here's what I had done for the Newt's Cape icon (after modifying the header output from NCGC):
```
ImageCache:NewtsCape 		
{URL: "string", type: "string", width: "int", bitmap: "bitmap"}
REPLACE!URL
http://communicrossings.com/html/newton/graphics/nwscpicn.gif	image/gif	32	!\
000151F8\
0000E3F0\
...
0E01F800
BYE!
```
can I have multiple schedules per folder or have scheduled items in 'All'? The main complication is how to name/differentiate items automatically and currently Newt's Cape uses the folder name to group items; items in All might be confusing since items could potentially be scheduled more than once.
how can I use Newt's Cape for form-based data collection? You can use HTML to represent your form, even including Newton-specific form objects to enhance the user interface. Of course, you can save data via the usual GET/POST methods to a web CGI server-side script. I've done some (unreleased) changes that could queue offline requests to submit later. It's also possible to save the data in Notes, or in a local soup -- then sync that back to desktop (using NCU or Xport or Sloup), or store in an email message for a later connect.