
README for GutenPalm version 1.41

by John Gruenenfelder (johng@as.arizona.edu)
Thursday, August 2, 2001

The definitive documentation is here:
http://gutenpalm.sourceforge.net



What is GutenPalm?
------------------------------

GutenPalm is a book reader for Palm Pilots.  Its main feature to differentiate
from the others is its database format.  GutenPalm uses zTXT databases instead
of DOC.  zTXT offers similar features plus much better compression.

My primary reason for creating GutenPalm was to a have a Free book reader that
uses good compression.  The books in question are from Project Gutenberg, a
terrific organization commited to have good literature available free to
everyone.  Visit PG at http://promo.net/pg.

GutenPalm is distributed under the GNU General Public License v2.  zLib,
however, is distributed under the zLib license.  Luckily the two are
compatible.  See the file COPYING for the text of the GPL, or view GPL.pdb
using GutenPalm.  See the file COPYING.zlib for the zLib license.


********************
** IMPORTANT NOTE **
********************

This will be the last release of GutenPalm under the *current* name.  Due to
corporate idiocy of my new least liked company, Palm Inc., the name will be
changing so that the word 'palm' is not in the title.  They are bad people.
The website and URL will either remain the same or have redirectors to the new
URL.  The most likely new name will be "Weasel Reader".

*******************
*******************



Requirements
------------------------------
* Palm OS 2.0 or better
* 2MB of memory
* PalmZLib (see below)


Quick Usage
------------------------------
1) Put gutenpalm.prc onto your Palm.
2) Grab PalmZLib from the download page at http://gutenpalm.sf.net.  GutenPalm
   requires it.
3) Grab some e-text's from Project Gutenberg (http://promo.net/pg)
4) Get makeztxt (or similar program, like jmakeztxt) from
   http://gutenpalm.sf.net
5) Run makeztxt on the text files (see the makeztxt README for more).
   For a quick example:
      makeztxt -t "Book Title" book.txt
   And it will output book.pdb for you.
6) Put the generated databases on your Palm
7) Read away!
8) I'd really like to hear your feedback. Send in bug reports please!
   (johng@as.arizona.edu)



Features
------------------------------
  * Reads zTXT databases
  * Uses zLib for compression (ala gzip and pkzip)
  * Decompress the text as you read (on-demand) or all at once
  * Uses an age-based cache to keep the most relevant data in memory
  * Remembers where you stop reading
  * Option to keep uncompressed data around to speed access
  * Full bookmark support.  Add/Remove/etc.
  * Jump around to arbitrary places in the text
  * Number of allowable texts is limited only by memory
  * You can select the text you're reading to copy it into other apps
  * Export text to the Memo Pad
  * Beam GutenPalm or zTXT books to other Palms or to a PC
  * Full annotation support with references to where the annotation occurs
  * Search capability
  * Smooth Autoscrolling ability
  * Disable the onscreen controls and read full-screen
  * Invert the screen
  * Rotate the screen by 90, 180, or 270 degrees
  * Per-document preferences (optional)
  * Supports read-only zTXTs in ROM/Flash/etc.
  * Absolutely 100% Free Software (licensed under the GPL 2.0)



Rational Behind GutenPalm
------------------------------
After having an opportunity to use a Palm (IIIxe to be precise) for a couple
months, I came to like them.  Nice and small, light, and enough power to do
quite a bit.  A tad short on memory, but that was about it.

Eventually I decided that I would like to have one to use as a sort of eBook
clone.  I had used AportisDoc Mobile edition and noticed that (surprise!) it
sucks a lot.  Much of this apparent suckiness was due to it being the free
version and being featured limited.  I wasn't really looking forward to paying
$30 for an ASCII viewer for the Palm.

There are other free viewers available, though, some of which are even Free
(with a capital F).  As an aside, if you really need a DOC viewer for your
Palm, I recommend CSpotRun.  Lots of features, and stable too.

Anyway, all the other viewers used the "open" PalmDoc format.  Open only
because somebody had reverse engineered it.  Aportis wasn't very forthcoming.
The problem is, PalmDoc is not very good for storing book length texts.
Well... it's not that good for storing much of anything.  The algorithm used
is similar in ways to zLib (zip/gzip), but not nearly as advanced.  What it
does have, however, is speed.  But, I'm willing to put up with a small
decompression time when it means saving about 33% in space over PalmDoc
(more the larger the text is).  After all, most Palm's have only 8MB of memory
or less.

So, I wrote GutenPalm.  You can get free e-texts from Project Gutenberg and
read them with a free reader, GutenPalm.



Fiddling with the Source
------------------------------
You'll need a suitable Palm developement environment.  GutenPalm was created
with Palm SDK 3.5, so you'll need a copy of that too.

You should look in the Makefile to make sure the program names and paths are
okay.
  "make"
You should now have gutenpalm.prc.

If you're messing with the source, then maybe you want to help.  If you have
any problems, feel free to email me at johng@as.arizona.edu .  Also, if you
plan to do anything with GutenPalm, be it coding, translations, or whatever,
please use the latest CVS copy.  It can be found on:
  http://sourceforge.net/projects/gutenpalm



Miscellaneous Notes
------------------------------
  ** The standard "it runs fine for me" disclaimer applies.  I've tested it a
     lot myself, but you can never predict everything.  Still, there's no
     oddball hacking involved so I think the chance of catastophic Palm
     explosion should be small indeed.  This is not to say that it won't ever
     crash/hang, but if it does...
