BookMaking Tips and Tricks

Elise Bowditch
bowditch@a-sharp.com

Copyright © 1994-1995 by Creative Digital, Inc. All rights reserved. This article is reprinted from the May 1994 issue of PDA Developers magazine, a bimonthly technical journal for programmers creating software for handheld devices. For more information about PDA Developers, contact Creative Digital at 415.621.4252 or cdi@cdigital.com.

The Newton Book Maker is a simple tool that you can use to take the information important to you and put it on your Newton. You don't need to be a programmer to take advantage of Book Maker, but a procedure for book making helps smooth the process. This article contains some guidelines, assembled over the course of a half dozen or so projects, that can make book making easier and help you produce better books. I discuss preparation, design, technique, testing and some routines you can copy and use in your own products.

The simplest way to describe bookmaking is:

Of course, you may envision something beyond basic text on a Newton and want to add some special features to your book. Maybe you're working with a huge data file and wondering if there is a better way to make a book than trudging through and marking up all that text. Or you're running into odd spacing once the file is on the Newton, and wonder what might be going wrong. This article helps you with these and other questions.

Note: In this article, places where you substitute your own names are noted within <>, as in ".story <YourStoryName>". The actual command you use would read ".story MyStoryName".

Don't Start Yet!

Just like a programming project, the cleaner the data is to start with, the better off you are. Don't even think about adding dot commands to text without doing a thorough data check. It doesn't matter if this literary gem was proofed by dozens before you -- the Newton Book is your product, so make sure it is as close to perfect as possible. It is easier to check the source data than to wade through an 80% completed book looking for small errors. Catching errors ahead of time lets you concentrate on creating the book.

A good word processor makes data cleanup easier. Check the spelling, of course. If possible, read or at least skim over the text looking for glaring grammar errors. Are capitals and mixed cases accurate and consistent throughout the text? If the text reads "Personal Digital Assistant" in one place, is it the same everywhere? What about acronyms (CDROM, CD-ROM) and hyphenated words (on-line, on line, online)? If the document has paragraph styles or style sheets, test a small subset of the text to see whether Book Maker recognizes the styles. If it does, you can leave them; if not you have to eliminate the styles and set the font, size and other text attributes directly. Eliminate or replace any special character fonts (such as bullets in Symbol font). A word processor with font and format based search ability in its find/replace function (such as Microsoft Word) is very helpful here.

Rule of Thumb for Space: The word processor document is approximately equal to the size of the final Newton Book. The package is usually about twice the word processor file size, but Newton compresses at around 2:1. This is rough, and varies depending on the type of information, but it should keep you from having to delete text near the end of the project.

Picky, Picky, Picky

These little things don't take much time to look for and fix. They aren't fatal, but taking care of them makes the final book look better.

Dashes and Hyphens

Check that dashes are either a short hyphen (as in high-falutin') or a long hyphen (m-dash, as in "the building was empty -- or so it seemed"). Get rid of manual hyphenations. A hyphenated word places differently on a Newton than it does on the desktop monitor showing the original text (plus you cannot search on a manually hyphenated word).

Spacing

If there are bullet points in the text, make sure that the spacing between the bullet and text is the same everywhere. Replace any non-breaking spaces with regular spaces. Non-breaking spaces are the result of using modifier keys with the space bar (such as command-space or option-space). They look like a dot with a tilde over top in Microsoft Word if you turn on Show Invisible Characters. Eliminate any spaces between the last period in a paragraph and the end of paragraph marker. Check for double spacing between words and sentences. Make sure that tabs and spaces are what they appear to be, and where you want them to be.

Other

Use smart quotes and apostrophes. Be aware that superscripts and subscripts look smaller on the Newton than they do in a word processor.

Basic Design

Fonts

Newton has two printable fonts: Geneva and New York. Espy Sans is available if you are not concerned about your users printing (it's only available as a bitmapped screen font on the Macintosh). A book looks better when the fonts are consistent for headings, kiosk choices and text. Text smaller than 9 points looks ugly (Newton measures it differently from Book Maker, even blank lines). Use pictures with 1-bit depth for fancy type styles in heading or introductory pages. HyperCard is handy for this. Create text in non-Newton fonts and paste in the picture in the layout. Inverting the text also gives a nice effect. For example: 
.layout <yourlayout name> 12 noTitle
.running picture

Pictures

All pictures should be crisp and legible in black and white. Don't try to use too subtle a picture, it will likely be lost on the Newton. Pictures are useful for gotos that the user taps to jump to some other part of the text. They also come in handy for storycards and headers.

A Word on Subjects and Levels

The browser acts as a built-in table of contents, picking up entries from the .subject commands. It's tempting to want to give users many subdivisions of the data so that they can go anywhere -- but too many levels is confusing and actually slows down the browser. Limit the browser to 3-4 levels maximum. One trick is to make browser topics for the contents of one or two pages of text (see Figure 1). Also, an alphabetical list doesn't necessarily need a separate entry for A,B...Z -- an entry for A-E, F-M...W-Z may work just fine.

Advanced Design

You can create good Books using just dot commands, but by using Book Maker with NTK programming can create some elegant effects. You don't need to be a programmer to use these, just substitute your own names where you see words enclosed by the characters "<" and ">". Thanks to Pensée Corp. for allowing these script and code samples to be included in this article.

Highlighting Kiosk Entries

A kiosk item is an item on a menu (kiosk) page that the user taps to go to the subject matter it represents. Kiosk items look better if they highlight, like buttons, when the user moves the pen over them and taps (see Figure 2). Add this script for each entry in a kiosk. 
.story goto=<wherever> NoExtend
.script viewClickScript
if (:TrackHilite(aClick)) then begin
    :buttonClickScript();
    :Hilite(NIL);
end;
TRUE;
.endscript
<KIOSK ENTRY>
The NoExtend flag prevents the last entry from highlighting to the bottom of the screen.

Storycards

Storycards are pop-up windows that display either text or pictures. They are displayed one at a time. Storycards are useful for showing small amounts of information in a window, without leaving the current page (see Figures 3 and 4). A storycard can contain text or pictures. Help functions, abbreviations and terminology definitions are good candidates for storycards.

The simplest script for using a storycard is: 

.script
:ShowStoryCard('<somename>, "<title>",
	{left: <w>, top: <x>, right: <y>, bottom: <z>});
.endscript
The .script command and the following information is added to the entry where you want the user to tap to show the storycard. w, x, y, z are the window's dimensions. With a book sized 240 pixels wide by 302 long, it may take a little experimenting to get the window properly placed.

Put the storycards' content near the beginning of the text, after the layouts and prior to the title page. If you have many storycards, performance is faster when they are near the beginning. A typical storycard would look like this: 

.story nopage
.attribute <somename>: "<title>"
<text>

Make Text Easy to Read

Don't be afraid to leave white space around entries. A crowded page is hard to read, even more so on an LCD display. Spaces between kiosk items, between columns, between headings and stories contribute to a better looking page. Use the .space command, but remember it needs a story (with content) both above and below it. A story is simply content that is not broken up by other commands. A story can be an entire document, a paragraph, several pages or a picture.

Break up stories with space or lines so that a solid text block doesn't confront the user on each page. Use the edgeTop and edgeBottom commands in the .story line to get solid lines. Dashed lines gently separate elements onscreen, and are less distracting to the eye than a solid line (see Figure 5.)

Add this script where you want a dashed line. 

.story layout=<yourLayout> edgeTop
.script slot drawPenPat
vfLtGray
.endscript

Navigation

If users can navigate into a book easily by hopping from one level to the next, can they move out of it just as easily? Someone perusing the book should be able to go back one level, two levels or to the top just as easily as s/he entered those levels. You can rely on the Newton bookmark dialog, but it's friendly and cool to put your own navigation into the book too. A .running picture in a layout shows the same picture for each page with that layout. With a goto in the form of .running picture goto=<destination>, the user can go to the same destination from each page with that layout. What if you want to use two (or more) icons in a layout and give the user several places to goto from each entry? For instance, a helpful navigation device is to include an icon to return to the main kiosk, and an icon to go to the current level kiosk (see Figure 6).

Here is a technique for using one picture to return to the main kiosk and another picture to go to the current level kiosk. The book commands to do this are fairly simply, but you need to do some preparation in NTK before you can use them.


First, create a ResEdit file containing the pictures for the buttons -- NTK and Book Maker reference this file. Next, in NTK, create a proto layout with a protoPictureButton for each picture in a clView. Name them descriptively, as in ToTopKiosk or ToKiosk_A. You don't have to place them accurately, since filling in the viewBounds takes care of precision placement (see Figure 7). Next, set the clView viewBounds (see Figure 8). Then, edit each protoPictureButton as follows:

* Each picture used to send the user to a kiosk gets an icon (select the appropriate picture from your .rsrc files) and a buttonClickScript like the following: 

// Parent slots:
// curRendering
// destPage
// kioskDest
func()
begin
// Get rid of storyCard before turning away (works around a bug)
if (storyCard <> NIL) then
    :HideStoryCard();

if (curRendering = 0) then
    // If we're the pre-built size, we know which page to turn to.
    :TurnToPage(destPage);
else
    // We've been re-layed out, so we'll have to search for the kiosk
    :TurnToPage(:FindPageByContent(kioskDest,0,NIL));
end

* Also, for each picture you need to set the viewBounds (this is where you place the picture precisely on the Newton screen) and the viewFormat (see Figure 9). Add a protoPictureButton and a viewSetupFormScript like this one: 
func()
begin
    self.icon := :Parent().icon;
end

* The picture used to send the user back to the main kiosk gets a buttonClickScript like the following: 
func()
begin
// Get rid of storyCard before turning away (works around a bug)
if (storyCard <> NIL) then
    :HideStoryCard();
:TurnToPage(1);
end
Enter the appropriate page number for the topmost kiosk; in most books, this is page one, unless you have a title or introductory pages.

* Also, give each picture an icon -- select the appropriate icon from your .rsrc files -- and a protoPictureButton). Finally, set the viewBounds and viewFormat (see Figure 10).

Finally, as your last step, you need to modify the Book Maker script. In the preamble, add 

// Opening the resource file for storycards
rRef := OpenResFileX(HOME & "<YourResEditFile>.rsrc");
In the layouts, add: 
.layout <YourLayout> noTitle
.running form height=20 width=240 goto=<YourKiosk>
{_proto: layout_<YourNTKLayoutName>, icon: 	
	GetPictAsBits("<YourIcon>", NIL)}
You can use your NTK Layout for different headers by creating a separately named Proto Layout in NTK and a separately name layout in Book Maker for each header. Insert the appropriate icon name in place of <YourIcon>. The icon that goes to the topmost kiosk is the same regardless of layout.

Making the Book

Use Naming Conventions

Spend a few minutes thinking about naming conventions to prevent confusion or duplication later. There may be groups of entries where each group needs a separate layout and kiosk, and each entry has a subject name and storycard. Create some naming conventions and stick with them.

Make the Marked Up Text Easy to Work With

Add lines around subjects and stories with the .# dot command that indicates a comment. I use .#---- for stories, .#====== for subjects and .#****** for kiosks. This makes them easier to find in a long text file. Use the comments to label large areas like layout declarations, storycard text and kiosks. I like to put my dot commands in a different font, larger and with the style set to bold, while working on the book, to make proofing easier. It is painful to search for a bad .story or .subject command that blends in with the text above it. Since this takes some discipline, don't forget that you might have missed a dot command or two when searching for errors.

When the book is done, tested and ready for its final version, change the non-Newton fonts to a Geneva or New York font set to bold or italic to keep them standing out. If they remain in their original font, there's no harm done, but the .f file will show unknown fonts. Though no one but the creator(s) sees the marked up text, highlighting the dot commands makes future changes easier.

Tips on Pictures

Measure pictures carefully. One pixel more or less can matter. Get pictures to fit exactly on the screen by counting pixels or use a snapshot of the Newton screen (from the Mac) as a guide in HyperCard. If the picture needs to float near (but not abutting) the top of the screen, include a few (or more) pixels of white space around the picture when selecting it from HyperCard (or wherever).

Start Small

Start with a minimal framework of kiosks and entries and edit and test these to perfection. It is much easier to work on a small file and faster, too, to run a prototype through Book Maker and NTK. A sample book is useful if you need an OK on the final design from someone. Once the kiosk and entry layouts are set, add the remainder of the text.

Testing

Yes, you need to test everything. Make a grid (on paper) of any pen points where the user goes to or leaves screens or enters data. Check each entry. Don't assume that because all 150 entries have the same dot commands, that each works identically. There can be small variations in data or typos in the dot commands that make the nth entry behave differently from the 1st entry. Test everything, including the browser entries, at least once. One nice thing about books is that there isn't a lot of regression testing; if it tested fine once, it should work again until you change its dot commands.

Step back and judge:

When you're all done, clean up the files and folders, save and date the latest versions. The minimum files to keep are the source file, the NTK project and any ResEdit file if there is one. You can always rebuild the .f files and package.

Databases and Books

Is the text of your proposed book a reference work containing many entries of similar format, like a birding guide or the sales line of all 500 widgets your company produces? If so, and if there are many entries, take some time to get the data into a database. I use FileMaker Pro, but any database that supports exporting records in merge file format should work. The word processor should have IF and ELSE merge commands to handle subjects at different levels (I use Microsoft Word -- other word processors should have commands similar to those I describe in this section). Write a merge file that creates your Newton Book script around the data instead of manually marking each of the multiple entries.

Check Your Data

Before you create your merge file you should check your source data. Make sure null values export as null values, not zeros, not the word "null" or "NIL". If you do your data cleaning properly this won't happen. Zip codes should be text fields in the database so that eastern states don't lose their preceding zeros. Decimal amounts need a preceding zero: 0.0 or -0.1, not .0 or -.1.

If the book has groups of data that need browser entries for each group, add a field (or fields) to indicate the first record for each group. Mark the first record in each group so that the merge commands will have something to test for writing the .subject command. See the Sample below, where the first and third records have Header = "Y" and produce the necessary .subject commands.

From Database to Book

Put your initial book commands and preamble in a separate file since merging operates on a for-each-record basis -- you only need these commands once. Create a word processing file containing the merge commands. Remember to put the right fonts, styles and sizes where the fields are printed since they print with whatever style the field has. Use a data inquiry command like "DATA ?" rather than specifying a complete filename such as "DATA <filename>" to give you the flexibility to experiment with a subset of the real data. Sort the data and export it in merge file format. It's important to test the data and merge commands on a small subset of records to see if there are any quirks in the word processor. For instance, smart quotes ("") in the text may give you problems when merging. My workaround is to replace " and " characters in the export file with characters not in that file, like å and ø (option-a, option-o). Once the merge is done, I change the å and ø back to " and ". If there are any m-dashes next to quotes, check that the quotes are correct.

Create a merge file that writes the dot commands around each record, and use the word processor merge command to create the bulk of the Newton Book. Edit the merged file to undo any workarounds that need undoing. Once you have a good merged file, cut and paste the one-time commands and the preamble into the file with and run the final result through Book Maker.

A Sample Database

Here's a small database with three records: 
	Record 1		
Header	Y	
Subject	Storage	
ItemName	Rewritable Optical Disks	
Price	32.00	
Story1	Massive Storage Capacity	
Story2	For your mass data & image 	
	storage needs

	Record 2
Header	N
Subject	Storage
ItemName	Tape Backup Media
Price
Story1	High Data Storage Capacity
Story2	Perfect for unattended backup

	Record 3
Header	Y
Subject	Displays
ItemName	Color Terminal
Price	350.00
Story1	8-bit color display
Story2
The merge commands I use to create my book file are: 
"DATA ?""IF Header="Y""
.# =============================
.subject 2 browseronly
"Subject"
"ENDIF"
.# -----------------------------
.subject 3
"ItemName"
.story startspage centered
"Story1"
"IF Story2 <> """.space 3
.story
"Story2""ENDIF"
Price:"IF Price <> """ $"Price""ELSE" n/a"ENDIF"
Here's the result of merging the two: 
.# =============================
.subject 2 browseronly
Storage
.# -----------------------------
.subject 3
Rewritable Optical Disks
.story startspage centered
Massive Storage Capacity
.space 3
.story
For your mass data & image storage needs
Price:$32.00
.# -----------------------------
.subject 3
Tape Backup Media
.story startspage centered
High Data Storage Capacity
.space 3
.story
Perfect for unattended backup
.story
Price:n/a
.# =============================
.subject 2 browseronly
Displays
.# -----------------------------
.subject 3
Color Terminal
.story startspage centered
8-bit color display
Price:$350.00

Go Make Books

If you're just starting to make books, play around with text and dot commands to get comfortable with Book Maker basics and see what happens when you use this or that command. Though you don't need a lot of technical expertise to make a book, you need to learn at least some of the commands and terminology. If you are already comfortable with basic book making, try some of the advanced routines. If you're a programmer, think about the relation between coding and book making (which is outside the scope of this article).

Create some sample books, just for fun, such as your family tree, ten favorite movies or something similar. Since Book Maker gives quick results it's easy to play and learn. When you're ready for a real book, you'll be prepared. We all want information on the Newton to be useful once it's there. A little practice, forethought about the design and attention to detail rewards the Book Maker with a book that conveys information in a way that's attractive and easy to use.

Last updated 4 Jan 00 eb

Info Plaza