Before creating/saving a help book, you should understand about its original (source) format:
and its processed (book) structure:
A help book can be created from Bookmaker syntax via NTK/BookMaker or a limited Newt capability
advantages: familiar to Newton developers? flexible layout
disadvantages: unique (non-standard) markup language; Bookmaker is Mac-only?; lack of other tools
help book created at run-time or accessed in package saved by Newt's Cape
advantages: standard; compatible with web-based documentation; many authoring tools
disadvantages: only Newt's Cape available for creating help books?
created from HTML source by Newt's Cape. see HelpURL example application.
advantages: flexible, customize the book to contain user- or context-specific information
disadvantages: slow, uses more heap; Newt's Cape only?
help book (created by NTK or Newt's Cape) accessed via its ISBN.
advantages: easier to update separately from application
disadvantages: more packages to install/manage
help book (created by NTK, Newt, or Newt's Cape) is part of application and accessed as slot directly in same package.
advantages: easier to distribute
disadvantages: more difficult to update
Add Bookmaker markup commands to a word processing document.
Creating a book requires Apple's Bookmaker (Mac only?) and Newton ToolKit (NTK). See Newton Bookmaker User's Guide for further information.
Newt provides a minimal capability to process two pseudo-Bookmaker markers ("Bookmaker0" indicates this subset):
This can be convenient for creating very simple help books. See NewtATut tutorial, picoferm.nwt example, and Newt manual.
It is possible to create your own (help) books programmatically using NewtonScript. This might be necessary for very unique layouts. However, this is not really documented or supported (and will not be discussed further here). See books.nwt example.
You can embed HTML source in your NTK or Newt application and later create a help book at run-time (assuming Newt's Cape is installed). See HelpURL example application.
Create HTML document (such as this one) in Notes (Newtworks, etc.); include multiple levels, formatting and links. Compared to a regular book, help book has content only in "leaf" pages; each page should be short (no scrolling); limited number of headings per level; links within a help book go to destination visible on topics page (you still need to select it to see content, for example Configuration (next section)).
Make sure you change "above" preference so that a H1-H6 heading starts at the top of a page, either locally in the document (see META) or globally via Options.
Set Page Size to Help, either globally via i:Appearance or via pageSize API option (see HelpURL example application).
You need to include several methods to initialize, open and close the help book. See NewtATut tutorial.
To add pages, use the "+page" Newt header syntax, for example:
MyApp.helpBook+page1 .subject 1 this is a subject .story this is some content
You could use Newt's Cape's :dispatchFile API with HTML source -- see HelpURL example application.
For Newt, you can create a help book in Newt's Cape from HTML source, or access an already saved book via its ISBN. To embed a temporary book created by Newt's Cape, in Newt, Eval:
myApp._proto.helpBook := GetRoot().|NewtsCape:NewtsCape|.curBook
Re-open (don't rebuild) app.
Before saving application (with help book) as a package, Eval:
GetRoot().|NewtsCape:NewtsCape|:removeApp(true)
Once you have the proper Page Size and Appearance options set, you can create a help book from an HTML document stored locally (Notes, Newtworks,...), from web, or via via dispatchFile API (see HelpURL).
The helpBook slot contains the help book. When you save the application as a package, it is embedded as part of the application.
An NTK application could contain the HTML (for run-time creation) or it could refer to a separate saved help book (package) on the Newton via its ISBN.
Like NTK, a Newt application could contain the HTML (for run-time creation), or it could refer to a separate saved help book (package) on the Newton via its ISBN.
It can also embed a Newt's Cape generated help book (see next).
You can save a separate help book package, and later access it via its ISBN from an NTK or Newt application.
You can also embed the interim help book data structure directly in a Newt application (package). See Saving:Newt (HTML)
This document (in all its formats) is © 1997-2007. Steve Weyer. All Rights Reserved Worldwide. You are free to incorporate this into your own documents, but I would appreciate an acknowledgement of Newt's Cape and the example.