How To Make NewtonBooks, Part Five - Compiling Your Books January 5, 1994 Copyright (c) 1994 Tony Lindsey, (xxltony@aol.com). The articles in this series may be copied freely, but may not be sold unless prior permission is obtained. PREREQUISITES FOR THIS ARTICLE I expect that you have downloaded the previous articles in the How2MakeNewtonBooks series. If not, please refer to the README.5TH file enclosed with this document to find out where they can be found. This is part of an ongoing series of articles. A clever person following this series should be able to use these articles to create simple books that can be read on a Newton MessagePad or other product with Newton Intelligence. I will be assuming that you are attempting the following steps on a Macintosh computer, IIcx or later, with a minimum of 8 megabytes of RAM, running System 7.1.. I also assume that you have Newton ToolKit version 1.0b7 and Newton Book Maker 1.0b7. MAKING SURE ALL OF THE PARTS ARE IN PLACE First, I will review the proper location of Newton ToolKit (NTK) components. The following instructions apply to version 1.0b7, and the instructions may change without notice. You're on your own, in that case. There are parts scattered in various locations, and you may not get predictable results if all of the pieces are not present and accounted for. If NTK is properly installed, then the System Folder should have the following files in the following locations: IN THE FONTS FOLDER (USING SYSTEM 7.1 or later): There should be a suitcase called Newton ToolKit Font. It's not strictly required for our BookMaking tasks. IN THE EXTENSIONS FOLDER: There should be two files that are needed: - Apple Modem Tool (version 1.5 should work file, but slightly older versions seem to work fine as well). - AppleTalk ADSP Tool (version 1.01 is satisfactory) I believe that these are only needed if you are planning to transfer the completed books over an AppleTalk connection. THE CLARIS FOLDER This is a very important folder within your System Folder. BookMaker needs this folder and its contents to read in word- processor files and interpret their commands for font and style changes. Claris (a subsidiary company of Apple Computer) created a system that provides a standardized method of reading and translating files that were created by completely different programs. The Claris folder is provided free with programs such as FileMaker, MacWrite and Claris Works. The Claris folder should contain the following items: - Claris XTND System (version 1.3.6 is nice), and - A folder called Claris Translators. THE CLARIS TRANSLATORS FOLDER This folder should contain files with names like these: MacPaint MacWrite Microsoft Word 3.0 Microsoft Word 4-5 Microsoft Word PC 4.0-5.0 Microsoft Works 1.1 Microsoft Works 2.0 Microsoft Works DB PICT TIFF WordPerfect These are the files that allow documents to be recognized and translated by BookMaker or any other program that uses the Claris XTND system. THE REMAINING FILES Newton ToolKit comes with scads of freebie files that are used to demonstrate and illuminate the glory of creating your own programs. I will ignore these demo files in my article, and will only mention the components required for compiling books: - Newton Toolkit (version 1.0b7 or later) - Newton Book Maker (version .0b7 or later) - a folder called "Platforms" THE PLATFORMS FOLDER This folder may contain a single file: - MessagePad (no version given) Or, as technology advances, and as more models of the Newton arrive with different-size screens, each one should have its own, appropriately-named file in the Platforms folder. I am guessing that this folder contains "cheat sheets" that inform NTK what size and resolution a Newton's screen may have. MODIFICATIONS TO THE NEWTON TOOLKIT 1.0B7 PROGRAM Before we continue, it might be a good idea to check to see what version of NTK we are using. Click once on the Newton ToolKit program and choose "Get Info" under the File menu. It might say Version: 1.0b7 (the seventh beta version of NTK). Later versions (such as 1.0) should not need the following bug fix. BIG BOOK BUG FIX Here's how the bug shows up: when compiling a long book (over about 300 pages, or about 200k in size), NTK runs out of "FrameStorage Heap" or some such thing, and suggests we increase it. Increasing memory to NTK does not solve this, because it still stops at the same place, refusing to proceed. This one has an easy answer: - Make a backup copy of Newton ToolKit - Open NTK with ResEdit - Hit the letter "H" on your keyboard. This highlights the "HEAP resource icon. - double-click on the HEAP icon. You'll see two choices. - double-click on each one, change its number to 2048, and close its window. - Quit from ResEdit. When asked if you want to save changes, choose "Yes" You should see no adverse effects. You are on your own. COMPILING YOUR BOOK Here is every step used to compile NewtonBooks. I am assuming that you have the final "GRANGE.DOC" file I included in the first collection of files in the How2MakeNewtonBooks series. I will use it in the following example: - Drag the fully-formatted MS Word file called "GRANGE.DOC" into BookMaker, and then click on the "Do it" button. -Wait awhile, then when offered the chance to save a file, click on the Desktop button and save the default filename. This file's name should automatically end with ".f" This creates an "intermediate" file, which can be thrown away later when the package-making process is complete. Example: "GRANGE.DOC.f" - Wait some more, and when the watch cursor disappears, quit BookMaker and then begin using Newton ToolKit. - When offered the chance to open an existing file, click Cancel. - Under the Project menu, choose "New Project" - Click on Desktop, and give the new file an appropriate name that ends with a .PRJ (shorthand for Project, and totally unnecessary, but it helps distinguish among many files). (Example: GRANGE.PRJ) This creates yet another "intermediate" file that we will be throwing away later. - Under the Project menu, choose Add Book File. Double-click on the filename that ends with ".f" This adds the only file we need for this project. - Under the Project menu, choose "Package Settings" - In the middle of the dialog box, you'll see "ChangeMe:Sig" This is where you are supposed to identify the package as well as yourself. The information you put here is what shows up in the "Remove Software" dialog on your Newton. The part that says "ChangeMe" should contain a nice, short version of the book's name. Try to keep it under nine characters. In the example of "The Adventure of the Abbey Grange", I chose to use "Grange" Apple has a registry of programmer's identifiers that go where the word "Sig" goes. For this example, the folks helping me with my many, many books would put "Grange:NewtBoy" NewtBoy is just a distinctive name I chose. - Click on "OK". There are other settings that could be changed, but they are outside of the purpose of this article, which is to make a book with as few steps as possible. - The final step: Under "Project", choose "Build Package" and then wait for the watch cursor to go away. - Quit from NTK. After that, do some cleanup... Throw away the GRANGE.f and GRANGE.PRJ files, and tidy up around the place. You should find a file called GRANGE.PROJ.PKG in the same location. That's your book! - Rename the book to adhere to the PC world's file-naming conventions. There should be a maximum of 8 characters before the period. In this case, it would be called "GRANGE.PKG." I specify renaming it this way because I assume that you want to share your new book with as many folks as possible. According to a recent MacWeek magazine article, 40% of all Newton owners use an IBM-compatible computer. WHAT TO DO WITH YOUR PACKAGE FILE Of course, the first thing you'll want to do is load it onto your Newton. There are several ways of doing so. I've found that the simplest way is to use the program called "Package Express" that comes with Newton ToolKit. - Make sure that your Newton is correctly connected to the Mac. I personally have my Mac, my laser printer and my Newton connected with three Farallon PhoneNet connectors. This AppleTalk connection allows me to reserve my Phone port for my modem. I'm assuming that you have the same setup. If so, make sure that you have two terminating resistors plugged into each end of your mini-network. They came free with the PhoneNet connectors. - If all physical connections are made, turn on your Newton - Tap on Extras - Tap on Connection - Make sure that "Macintosh LocalTalk" is selected - Tap on "Choose Macintosh" - On the Mac, drag GRANGE.PKG into Package Express's icon. As soon as you see the striped bar moving in the dialog box, grab the Newton. - On the Newton, look to see if your Mac's name shows up as highlighted text. If so, tap on "Connect." If not, tap on "More Choices", wait for your Mac's name to show up, and then tap "Connect". If NO name shows up, maybe you never got around to naming your Mac. To name your Mac, you need to quit from Package Express, pull down the Apple menu, go to your Control Panels, choose Sharing Setup, fill in the first and third fields, close the window and then restart the Mac. This tells System 7 to start announcing itself on networks when asked to by programs like Package Express. After restarting, try these steps again. - After tapping "Connect" you might see an error message on the Mac. This is utterly normal with the Package Express that came with NTK 1.0b7. Just hit the Return key on your keyboard and the book should load just fine. You could also use Newton Connection Kit or Newton ToolKit to load the book package, but this is the simplest technique. CHECKING FOR FLAWS IN YOUR BOOK Assuming that you have gotten this far successfully, you should be able to tap on your Newton's Extras drawer icon. I am assuming that you have compiled the GRANGE.DOC file I included with my first article in this series. I will now provide a checklist of flaws to watch out for: - You should see a book icon with a SHORT (maximum 10 characters) name beneath it. If it's any longer, it won't be readable when other packages have long names on either side. This can be changed by modifying the .shortname dot command in the GRANGE.DOC file and recompiling. - Tap on your book's icon. You should see an attractive title page (with a nice picture of Sherlock Holmes if you're looking at GRANGE.PKG). There should be no tiny, bold title at the extreme top line of the first page. If there is, try adding the "notitle" modifier to the title page's .layout command, like this: .layout title 12 notitle - Tap the Overview dot between the arrows at the bottom of the Newton's screen. You should see the book's title and the "Publisher's Notes" if you are looking at GRANGE.PKG, or a nice collection of chapter headings if you are reading a book with chapters. - Close the Overview drawer, and tap the down arrow to flip through the book's pages. You should have no trouble reading the text, due to tiny size or awkwardly-laid-out paragraphs. The text should be easily readable. I personally favor the 12- point Fancy (New York) font. It means more pages, but you should never assume that everyone has eyesight as sharp as yours. There are a lot of aging Baby Boomers out there! If possible, hand the book over to a friend for proofreading. I admit I've neglected this step in the past. After working on a book for a long time, I hate to stare at it to look for flaws. My eyes cross, and I want to go take a nap. A friend will help you spot stuff like "Sherlock Holrnes" , which is an actual typo I missed the first time around. - Check to see if there any text is italicized. If so, take a good look at how awful it appears. Avoid it at all costs! I know that bold or underlined text is a poor substitute, but give it a try. Alternately, consider using the Simple (Geneva) font as a final possibility. - Paragraphs should have a blank line between them. If you leave these out, the text becomes uniform, with no visual breaks for your eyes to distinguish where they are. If you glance away, the act of looking for your place again becomes a chore. - Check to make sure that chapters break up the text properly. I have seen NewtonBooks that were never checked for this, and the end of one chapter and the beginning of another didn't look right, with blank pages or run-on text. - Look for curly quotes and apostrophes. They are optional, but the details do count. Look for double-hyphens. They should not exist, instead having been replaced by em-dashes. The Newton has the design goodness to include these, so why not use them? I'm sure that there are many, many other things that could go wrong with your books, but only you can spot them, since you are the publisher of your own books. Use your own standards, but do your best! WHY YOU SHOULD SHARE YOUR BOOK WITH THE WORLD Let's say that your newest NewtonBook is a work of art. You're proud of what you have done, and you want to share it with as many folks as possible. I have found America Online's Palmtop Paperbacks section (Go to Keyword "PDA") to be the largest library of NewtonBooks in existence as of this writing. I would like to ask you to share your books because it helps many, many more people than you could imagine. Think of a classroom full of kids in 1996, using the "Tom Sawyer" book on their inexpensive slate computers. The teacher would tap a single button on a screen, and every child would get a copy of the book at that moment. I leave it up to YOU whether you want to ask for a shareware fee, or keep the book as free as the breeze. Personally, I'm very idealistic, and have never asked for a fee for any of the books I've created. I've been downloading texts from America Online and other bulletin boards, and re-issuing them in NewtonBook format. I feel that it would be wrong for me to take another person's work and charge for it. Some day, I will be writing my own books in NewtonBook format, and I haven't yet figured out the way I'll merchandise them. CREATING AN INFORMATION FILE I have a lot of experience with uploading articles and other creations. They have a way of whisking out of your control in ways that you would never expect. People may download your file long after you have forgotten about it, in places like Singapore and the Ukraine. I think of myself as a mother sea turtle, who distributes her eggs and never sees them again. If this concept doesn't bother you, you should consider the needs of the folks who get your document. FILE NAMING CONSIDERATIONS If you are willing to share the book you've created, you should consider non-Mac Newton users. They can't always deal with long filenames with funny characters or spaces. They also need to acquire the book file in a compressed format that they can decompress with no problems. I always include an INFormation file with my books. I also compress the two files with Stuffit Deluxe. I also might include the original word-processing file I used to create the book, just so beginners could study how I did it. You can see an example of this on AOL in the "Nude Beaches of California" file I uploaded. When creating an INFormation file, I make sure it's a PC- compatible ASCII text file with linefeeds. I explained how to do this at the end of FILTER.DOC, which is part of the How2MakeNewtonBooks #3 article on AOL. I also make sure it has the same sort of name as the book. For example, I would have a book called "GRANGE.PKG", and an INFormation file called "GRANGE.INF." I would use Stuffit Deluxe to store the both of those files in an archive called "GRANGE.SIT." I like Stuffit Deluxe because it's available on both the PC and Mac platforms, and America Online will automatically decompress the files after downloading. Compressing the files saves money spent on downloading time, and it keeps the appropriate files together. Stuffit Deluxe is available from many mail-order and software retailers. Using Stuffit Deluxe, I would choose "New" under the File menu, type in a filename like GRANGE.SIT, and then click on the "Stuff" icon. I would then double-click on GRANGE.PKG and GRANGE.INF. and then click on the "Stuff" button. After quitting, I'm ready to upload the GRANGE.SIT file. UPLOADING ONTO AMERICA ONLINE I upload my files by following this procedure: I sign on to AOL, and choose "Key word" under the "Go To" menu. Type "PDA" and hit return. Click on "New Files & Free Uploading" and click on the "Upload File" button, and fill out the form. If you're not sure how to phrase any of the words you put in these fields, just copy what I've done with any of my files like "Nude Beaches of California". ------------- This concludes the first five installments of this series. I have tentatively planned a sixth article for some future date, including a few corrections and additional tips. I will also make it my business to learn more dot commands. I will be uploading more-elegant books, but I will also enclose the documents I used to create these books. I hope that this will encourage others to publish ever-nicer books. I don't know what the future holds, but it is my fervent wish to see massive numbers of books available for the people of the world. Let's all do our part! Tony Lindsey, San Diego, California, Wednesday, January 5, 1994.