RichReader

A Rich Text Format (RTF) Document Reader
for the Palm Computing® Platform

Michael Arena
arenamj@erols.com

NOTE: The most recent documentation can always be found at the web site (it also has lots of screen shots!):
http://www.erols.com/arenakm/palm/RichReader.html

Introduction
RichReader is a document reader application for Palm Computing® Platform handheld devices (such as the PalmPilot Pro and the Palm III). Unlike other document readers, the power of this program is its ability to display richly formatted text from any word processor that can create Rich Text Format (RTF) files or HTML files. Document readers display text documents that are stored on the handheld device.  RichReader can also read plain documents (without formatting codes) stored in standard AportisDoc™ format.  This format is efficient for platforms with limited memory requirements since documents are divided into smaller, more manageable pieces and can be compressed significantly to save space.

If you are viewing this document on your handheld, you can already see the benefits that RichReader provides over standard plain text document readers. Words are displayed in various styles and sizes.  Paragraphs can be indented, justified, and have preceding bullets/numbers.  Not only do these highlights draw your eye to significant elements on the screen, but they also can improve comprehension of the author’s intent for certain words and phrases. For example (to borrow Sun’s catch phrase), if you read the sentence:

The Network Is The Computer™.

as plain text, it has a slightly different interpretation (to me) than when you read it as:

The Network Is The Computer™.

I developed this program to enhance productivity while away from the desktop PC. After I started using my PalmPilot Professional to take notes at meetings while following along in a printed document, it seemed obvious that I should be able to become even more “paperless”. As a professional in the information age you send and receive documents (probably Microsoft® Word documents) through email and can only view those documents while you are at your PC (or laptop). When you need to bring a document to a meeting, you need to print it out, take it to the meeting, write notes and changes on the pages, bring it back to your desk, type the notes in and email the comments to the original author (or edit the original) document, and, finally, discard that ream of paper that was only needed for a couple of hours.

If you own a handheld computer, you could streamline some of these steps by taking notes on the handheld (like in the Memo Pad) and then synching the changes back to your PC which can then be pasted into the document or an email. If you have a Document Reader on your handheld and some text conversion software (such as makedoc8 or MakeDocW), you could save the Microsoft® Word document as a Text file, and then convert it to a .prc/.pdb file to be synched with the handheld. Then you be able to read the unformatted text during the meeting and take notes in the Memo Pad. You have saved some trees but are still limited to plain text.

Therefore, the purpose of RichReader is to preserve most of the special character and paragraph formatting of documents so that the document is easier to read and comprehend on a small screen device. You now have the ability to bring any formatted document with you in your handheld so you can prepare for meetings wherever you are, not just at your desk. RichReader is also meant to be an inexpensive replacement for other document readers which you may own.

RichReader Features
•	Five different font styles:
Normal, Bold, Italic, Bold Italic, Fixed
All styles work with all font sizes (except there is no Small Bold).
•	Three different font sizes in proportional and fixed widths:
•	Small (<10 points) (7 pixels high, up to 22 lines per screen)
Normal, Bold, Italic, Bold Italic
Normal, Bold, Italic, Bold Italic
•	Medium (10-13 points) (11 pixels high, up to 14 lines per screen)
Normal, Bold, Italic, Bold Italic
Normal, Bold, Italic, Bold Italic
•	Large (14+ points) (14 pixels high, up to 11 lines per screen)
Normal, Bold, Italic, Bold Italic
Normal, Bold, Italic, Bold Italic
•	Solid underlining and dotted underlining (for links?). 
•	Three styles of paragraph justification:
Left justification is the most common.  Lines will wrap at 160 pixels which is the width of the Pilot screen.
Centering for titles.
Right justification also works.
•	“Long Word” wrapping
Some lines that end in very long words can sometimes wrap after only a few characters in other programs:
This is an
extremely-long-nonsense-word-with-no-embedded-spaces.
But this seems wasteful so if the long word starts before about 58% of the width (95 pixels), then it will simply break the word like so:
This is an extremely-long-nonsense-word-with-no-embedded-spaces.
•	Horizontal lines:Œ
test
Œend test
•	Tables are displayed one cell at a time with a horizontal line at the start and end of each row and a horizontal line at the end of a cell.  Therefore, when viewing a table in RichReader, you can distinguish row boundaries by "thick" lines and cell boundaries by "thin" lines.
Product	Version	Price	
RichReader	1.52	$14.95	
RichWriter	?.??	$??.??	

•	Added the Euro symbol (€) at character 128 in the Small and Medium fonts (not the Large font).
•	Paragraph Indenting
This paragraph is left indented one inch.  The first line indent is set to zero so all lines are indented identically.
This paragraph is also left indented one inch but the first line is indented another one half inch relative to the left indent.
This last paragraph is also left indented one inch but the first line is negatively indented one half inch relative to the left indent.
•	Document information is saved between sessions
•	When a document is first opened, it is scanned for certain properties (this can take a while for large documents).  This information along with the current line number is saved in a database so that when leaving the application and then returning, the program will quickly return to where you left off.
•	Bookmarks
•	Bookmarks from the original RTF file will be converted to special tags in the Palm document.
•	Bookmarks saved by "another" Doc reader will also be scanned and added to the list.
•	Manually Add and Delete bookmarks
•	When Adding a bookmark, the first 15 characters of the top line of the screen are automatically copied to the Name: in the dialog.
•	Up to 200 bookmarks can be displayed.
•	Find
•	Allows you to search a document for a given string (up to 15 characters).
•	The line containing the matching string is displayed on the top line of the screen.
•	Case of letters are ignored (i.e. a = A)
•	All formatting is ignored
•	"Whitespace" characters are all considered equal.  You can enter a Space in the Find string and it will match a Space, Tab, Newline, or Carriage Return in the document
•	Wildcards!  The question mark (?) and period (.) characters in the Find string match any character in the document.
•	The search can be started from the Top of the document or from the Current Position.
•	View document in a single font style/size
•	There are two options on the Command menu which allow you to view “plain” text documents with one of the many permutations of fonts.  You can also “force” a “rich” document to be displayed in a single font/style (although why would you want to ;-).  
•	First, choose the Select Font menu item from the Command menu.  This brings up a screen that displays the entire font character set.  You can change the font size (Small, Medium, or Large) and set any combination of Bold, Italic, Underline, Fixed, and/or Link.
•	Then Close this screen (through the menu button).
•	Next, select a document in the Main screen, tap the Menu button and then choose the View with Selected Font item from the commands window.
•	NOTE: Currently, every time you choose View with Selected Font, this will recalculate the document formatting (even if it had been done previously) which means it could take a while for large documents and you will lose all manually added bookmarks.  However, if you keep the document open, switch to another application, then switch back to RichReader, then no recalculation will be done.  If you use the normal View command you don’t have to worry about this.
•	Rotate the screen
•	You can rotate the document View screen 90° Clockwise or Counter-Clockwise (see description of Preferences below).
•	The Main screen and all pop up dialogs and menus will not be rotated.

Operation
RTF2Doc, WRTF2Doc, HTML2Doc
RichReader accomplishes the above features by using embedded formatting characters in the text and by using bitmap fonts to supplement the built in fonts of the handheld device.  The formatting characters are embedded using the command-line program RTF2Doc or the Windows program WRTF2Doc which will read a Rich Text Format .rtf file and convert it into a compressed AportisDoc™ format .pdb file with embedded formatting.  In order for RTF2Doc and WRTF2Doc to run (as described in the included Install.txt file) you must modify/add two Environment Variables in the file C:\AUTOEXEC.BAT before running either program.  Assuming that you have installed the contents of the ZIP file into the directory C:\RichReader, then add the following two lines at the end of the AUTOEXEC.BAT file:
set PATH=%PATH%;C:\RichReader
set RTFLIBDIR=C:\RichReader
From the MS-DOS console window, you can run RTF2Doc.exe:
Example: Assuming that you have created an RTF file from your word processor (MyDoc.rtf), then (at the DOS prompt) type (everything after the C:\> prompt):
C:\>RTF2Doc MyDoc.rtf
Input RTF file:     MyDoc.rtf: 30.5 kb
Temporary TXT file: MyDoc.txt: 21.5 kb
Output PDB file:    MyDoc.pdb: 11.4 kb

This will create an output file in the same directory called MyDoc.pdb with the title "MyDoc".

You can also manually specify a title (which appears in the Main window in RichReader):
C:\>RTF2Doc C:\Documents\MyDoc.rtf "My Document"
Input RTF file:     C:\Documents\MyDoc.rtf: 30.5 kb
Temporary TXT file: C:\Documents\MyDoc.txt: 21.5 kb
Output PDB file:    C:\Documents\MyDoc.pdb: 11.4 kb
This will create an output file in the directory C:\Documents called MyDoc.pdb with the title "My Document".  NOTE: It is important to enclose the entire title in double quotes (").

You can also have RTF2Doc automatically install the output file in your HotSync directory and set the registry flag for the HotSync operation by using the “-i”  option:
C:\>RTF2Doc -i MyDoc.rtf “MyDoc”
Input RTF file:     MyDoc.rtf: 30.5 kb
Temporary TXT file: MyDoc.txt: 21.5 kb
Output PDB file:    C:\pilot\ArenaM\Install\MyDoc.pdb: 11.4 kb
Installing file for HotSync user: Michael Arena

The Windows program WRTF2Doc.exe is in its first release.  It is a simple dialog application which prompts for a file name (using a standard file explorer dialog).  It will automatically format the output filename (.pdb) and set the title to the base filename (without the path and extension).  Then, you can change the title if you wish.  Then hit the Convert button.  After a brief pause (sorry, no progress indicator yet), a results dialog will pop up which shows the sizes of the input, output, (and temporary text) files so you can see the results of the compression (and how verbose RTF format is!)
NOTE: WRTF2Doc.exe was built using Visual C++ 4.0 which means you will need two Microsoft libraries (Mfc40.dll and Msvcrt40.dll) to be installed in the directory C:\Windows\System (or in C:\Winnt\System32 if on Windows NT).  If these files do not already exist on your system, then send me an email and I will send you the DLL’s.

The console program HTML2Doc.exe is very similar to RTF2Doc.exe.  You specify the input HTML file, a title, and optionally the “-i” flag for automatic installation of the output file for HotSync:
C:\>HTML2Doc -i MyDoc.html “MyDoc”
Input HTML file:    MyDoc.html: 30.5 kb
Temporary TXT file: MyDoc.txt: 21.5 kb
Output PDB file:    C:\pilot\ArenaM\Install\MyDoc.pdb: 11.4 kb
Installing file for HotSync user: Michael Arena

RichReader
Once the document has been synched to the handheld, it will be displayed in RichReader’s Main screen.  Select the document you wish to view from the list (scroll the list if necessary).  The date the document was loaded is displayed along with its size in kilobytes.  Select the View button to view the document in the View screen.  The Main screen has two menus.  The Commands menus displays View, View with Selected Font, Select Font,  and Reinitialize.  View is identical to the View button.  Select Font displays a form which lets you examine a full character set in any of the sizes and styles listed above.  Reinitialize is used to discard saved information about documents and fonts.  This information will automatically be recalculated when necessary.  The Options menu displays About, Preferences, and Register.  About displays the version of RichReader.  Use this number when registering.  Preferences displays a dialog where you can change the behavior of certain features of the program.  Currently, there are two options.  One is to set the behavior of tapping the screen in View mode.  A tap can either scroll one page (up or down) or one line (up or down).  The other is to set the Rotation of the screen when displaying a document.  Choose None for normal display.  Choose CW to rotate the screen Clockwise which means the hardware buttons will be in your right hand. Choose CCW to rotate the screen Counter-Clockwise which means the hardware buttons will be in your left hand (NOTE: The meaning of the PageUp and PageDown keys is reversed in this orientation).  Register displays a dialog where you enter the registration key.  Once the payment information has been received by me from PalmPilotGear HQ (which includes your HotSync username and RichReader version number), I will email you your registration key.  Unregistered versions of RichReader will only display about the first 8-9 screens of a document.  However, the unregistered version will allow you to view the entire RichReader Doc (RichReader.pdb) included with the distribution.
The View screen has two areas: the document window and the status/control window.  Use the Page Up and Page Down hardware buttons to scroll up and down the document window one page at a time.  The last/first line of the previous screen is preserved automatically.  Tapping in the upper half of the document window will move up the document one line.  Tapping in the lower half of the document window (except in the status/control area) will move down the document one line.
The status/control area contains a lot of information:
•	The CLOSE button will close the document and return to the Main window.  
•	The position of the current screen expressed as a percentage.
•	The solid left arrow behaves the same as the Page Up button.
•	The scroll bar that visually displays the position of the current screen within the document.  A “thumb” denotes the current position.  Tap a location within the scroll bar to move the “thumb”.
•	The solid right arrow behaves the same as the Page Down button.
•	The Bookmark button (page with corner folded icon) to activate the Bookmark function.
•	The Find button (magnifying glass icon) to activate the Find function.
•	The Find Again button (small magnifying glass with forward arrow icon) to activate the Find Again function.

Future Enhancements
The following enhancements are planned for the next several minor releases:
•	Bookmarks
•	In the future, auto-scanning for bookmarks using the <X> convention at the end of a document may be supported.

The following are some ideas for potential enhancements in future major releases.
•	Superscript and Subscript
•	Examples: 1st Place, xi = y2.
•	Conversion from HTML to AportisDoc™ format.
•	Links within a document
•	Tapping on a link could jump to an existing bookmark (anchor) within a document.
•	Annotations
•	Annotations would provide the ability to attach small notes to a document (analogous to writing notes in the margin).
•	Farther in the future, possibly add the ability (through a conduit) to have the annotations transferred back to the PC so that they could be incorporated back into the original document (manually).
•	Convert Microsoft® Word documents to AportisDoc™ format directly (instead of saving to RTF first).
•	Auto-conversion and synching
•	You could set up a directory on the PC such that any .rtf files which are saved in this directory will automatically get converted and sent to the handheld when synching (using a conduit to do all the work).  The only manual step is coping (or saving) the RTF file to the special directory.

I would welcome any other suggestions for enhancements or changes to existing features.

Acknowledgments
•	The RTF2Doc program is based on: 
RTF Tools, Release 1.10
6 April 1994 Paul DuBois dubois@primate.wisc.edu 
•	Almost the entire file makedoc7.cpp by Pat Beirne, Harold Bamford, and Rick Bram has been included in all of the conversion programs.
•	The decompression algorithm in RichReader was based on information from the CQ Codeworks: The Doc Format page by Rob Tillotson robt@debian.org: http://www.concentric.net/~N9mtb/cq/doc/format.html and from makedoc7.cpp (from above).
•	James Clark’s (jjc@jclark.com) SP package was used for HTML parsing.
•	The source for the HotSync install process in the conversion programs was from Mark Pierce.

RichReader Copyright © 1999 Michael Arena.  All rights reserved.
All other trademarks and registered trademarks are the sole property of their respective owners.
http://www.erols.com/arenakm/palm

License Agreement
RichReader (the "Software")

"You" means the person or company identified below, who is being licensed to use the "Software" identified in the title of this License Agreement. "We" and "us" means Michael Arena. 

Limited Nonexclusive License

You acknowledge that you are acquiring only a limited nonexclusive license to use the Software (the "License"). We remain the owner of all right, title, and interest in the Software and in any copies of it. 

The License permits you to install the Software (RichReader.prc and RichFonts.prc file) on more than one computer system, each with a unique user name, provided that a separate license for each computer system is obtained for each user.

You may distribute and/or copy the PC executables RTF2Doc.exe, WRTF2Doc.exe, and HTML2Doc.exe and their support files (*-gen, *-sym, and *-map) without restriction.  

You agree not to engage in nor to permit the decompilation, disassembly, or other reverse engineering of the Software. 

Limited Warranty

We warrant to you that, for a period of 14 days after delivery of this copy of the Software to you: 

1.the physical media on which this copy of the Software is distributed will be free from defects in materials and workmanship under normal use, 
2.the Software will perform in accordance with the printed documentation distributed with it by us, and 
3.to the best of our knowledge your use of the Software in accordance with its printed documentation will not, in and of itself, infringe any third party's copyright, patent, or other intellectual property right. 

To the extent permitted by applicable law, THE FOREGOING LIMITED WARRANTY IS IN LIEU OF ALL OTHER WARRANTIES OR CONDITIONS, EXPRESS OR IMPLIED, AND WE DISCLAIM ANY AND ALL IMPLIED WARRANTIES OR CONDITIONS, INCLUDING ANY IMPLIED WARRANTY OF TITLE, OF NONINFRINGEMENT, OF MERCHANTABILITY, OR OF FITNESS FOR A PARTICULAR PURPOSE, regardless whether we know or have reason to know of your particular needs. 

No employee, agent, dealer, or distributor of ours is authorized to modify this limited warranty, nor to make any additional warranties. 

No action for any breach of the above limited warranty may be commenced more than one (1) year following the expiration date of the warranty. 

If implied warranties may not be disclaimed under applicable law, then ANY IMPLIED WARRANTIES ARE LIMITED IN DURATION TO 90 DAYS AFTER DELIVERY OF THIS COPY OF THE SOFTWARE TO YOU. 

Some states do not allow limitations on how long an implied warranty lasts, so the above limitation may not apply to you. 

This warranty gives you specific legal rights, and you may also have other rights which vary from state to state. 

Limited Remedy

Your exclusive remedy in the event of a breach of the foregoing limited warranty, TO THE EXCLUSION OF ALL OTHER REMEDIES, is set forth in this paragraph. 

In such event, you shall return all copies of the Software to us and pay for shipping; you must include a dated proof of the date on which this copy of the Software was delivered to you, such as a copy of your dated receipt or invoice for this copy. 

We will, at our option, either (i) ship you a replacement copy of the Software on nondefective physical media at our expense or (ii) refund your license fee in full. 

To return copies of the Software, contact us at 781-863-2071. 

No Incidental or Consequential Damages

Independent of the foregoing provisions, IN NO EVENT WILL WE BE LIABLE TO YOU FOR ANY INCIDENTAL, SPECIAL, PUNITIVE, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING BUT NOT LIMITED TO DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, AND THE LIKE) ARISING FROM OR CONNECTED WITH THIS AGREEMENT OR YOUR USE OF THE SOFTWARE, regardless whether we know or have reason to know of the possibility of such damages. 

Some states do not allow exclusion or limitation of incidental or consequential damages, so the above limitation or exclusion may not apply to you. 

Your Indemnity to Us

Independent of the foregoing provisions, you agree to defend and indemnify us against, and hold us harmless from, any and all claims, damages, losses, and expenses of any kind arising from or connected with the operation of your business. 

Termination

If you materially breach this License Agreement, we may terminate your right to use the Software by notice to you. 

You agree that, upon termination of the License, you will either return to us or destroy all copies of the Software in your possession. 

Entire Agreement, etc.

This written License Agreement is the exclusive agreement between you and us concerning the Software and supersedes any and all prior oral or written agreements, negotiations, or other dealings between us concerning the Software. 

This License Agreement may be modified only by a writing signed by you and us. 

In the event of litigation between you and us concerning the Software, the prevailing party in the litigation and the prevailing party in any ancillary disputes (e.g., discovery disputes) will be entitled to recover attorneys' fees and expenses from the other party. 

This License Agreement will be governed by the law of the State of Massachusetts applicable to contracts executed and performed entirely in, and by residents of, that state. 

This License Agreement is effective upon the earlier of (1) your signature below, or (2) your use of the Software (provided that your acquisition of a copy of the Software was from us or our representative); you agree that we need not sign this License Agreement in order for it to take effect.
•