
README for GutenPalm version 1.0b1

by John Gruenenfelder (johng@as.arizona.edu)
Saturday, September 16, 2000

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.



Quick Usage
------------------------------
1) Put gutenpalm.prc onto your Palm.
2) Grab some e-text's from Project Gutenberg (http://promo.net/pg)
3) Run dos2unix or a similar CR/LF conversion program on the TXT files
4) Run makeztxt on the converted txt files (see the makeztxt section!)
5) Put the generated databases on your Palm
6) Read away!
7) Send in bug reports please! (johng@as.arizona.edu)



Features
------------------------------
GutenPalm:
  * Reads zTXT databases
  * Uses zLib for compression (ala gzip and pkzip)
  * 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

makeztxt:
  * Creates zTXT databases
  * Use regular expression to automatically generate bookmarks



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" DOC format.  Open only because
somebody had reverse engineered it.  Aportis wasn't very forthcoming.  The
problem is, DOC is not very good for storing book length texts.  Well... it's
not that good for storing much of anything.  It uses, from the code I've seen,
a "run length encoding" scheme to compress the text.  If you know what RLE is,
then you probably know that it's not the best thing to use to compress the
written word.  What it does have, however, is speed.  But, I'm willing to put
up with a 20 second decompression time when it means saving about 33% in space
over DOC (more the larger the text is).  After all, the largest current Palm's
only have 8MB.

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



Using makeztxt
------------------------------
makeztxt is a simple commandline program that takes a plain ASCII text file
and compresses it into a zTXT database.  It doesn't like the DOS style CR/LF
line breaks, so the input file should be first run through a conversion
program such as dos2unix if it contains such characters.  makeztxt will remove
newline characters at the end of lines that contain text so that the
paragraphs flow better on the Palm screen.

The best feature of makeztxt, however, is its ability to use regular
expressions to search the input text for bookmark spots.  This is done with
the command line options -l and -r.
  -l will list all the bookmarks that are generated.
  -r takes a regex as an argument to generate one or more bookmarks.
     You can have as many -r options as you want.

The following examples show the name of the work, the command line used, and
the first eight bookmarks generated by the command line:

Shakespeare's "King Henry V"
makeztxt -l -t "King Henry V" -r "DRAMATIS PERSONAE" -r "ACT [A-Z]+"
         -r "SCENE [A-Z]+" 2ws2310.txt
Generated bookmarks
Offset          Title
-----------     --------------------
12097           DRAMATIS PERSONAE
14841           ACT FIRST
14853           SCENE I
19241           SCENE II
33233           ACT II
35118           SCENE I
40805           SCENE II
49553           SCENE III

RL Stevenson's "Treasure Island"
makeztxt -l -t "Treasure Island" -r "PART [A-Z]+" -r "          [0-9]+"
         treas10.txt
Generated bookmarks
Offset          Title
-----------     --------------------
12005           PART ONE
12422           PART TWO
12836           PART THREE
13087           PART FOUR
13685           PART FIVE
14102           PART SIX
14656           PART ONE
14723           1

Charles Darwin's "On the Origin of Species"
makeztxt -l -t "On the Origin of Species" -r "Introduction\."
         -r "Chapter [IVX]+" otoos10.txt
Generated bookmarks
Offset          Title
-----------     --------------------
19482           Introduction.
29724           Chapter I
99693           Chapter II
129257          Chapter III
165118          Chapter IV
259640          Chapter V
332498          Chapter VI
399182          Chapter VII



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.

GutenPalm uses zLib v1.1.3 (http://www.info-zip.org/pub/infozip/zlib) and the
zLib Palm OS patch
(http://www.info-zip.org/pub/infozip/zlib/contrib/zlib113-palm.patch).
Compile zLib.  This should be pretty straight forward.  Keep in mind that
depending on your version of PRC Tools, 'make' may fail.  It should create the
static library, libz.a, but not the Palm shared library.  This is fine, you
only need the static lib.  Make the following links or renames:

  libz.a   -->  libz-m68k-palmos.a
  zconf.h  -->  zconf-palmos.h
  zlib.h   -->  zlib-palmos.h

This is to reduce confusion as to which copy of zlib is being used by
GutenPalm and which by makeztxt.  So, to clarify, GutenPalm uses a
staticly linked copy of zLib compiled for m68k-palmos.

To make life easier, a copy of zLib compiled for m68k-palmos is included with
the source distribution of GutenPalm as well as in the CVS tree.

You will also need to have zLib compiled for your HOST machine.  All Linux
distributions as well as most other Unices come with zLib, though it is
possible you may be lacking the zLib header files.  This copy of zLib will be
used when compiling makeztxt.

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

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



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...

  ** Somebody just created a Palm shared library for zLib
     (http://palmzlib.sourceforge.net).  I'll look into using it, though it
     seems to make some restrictions that I've not.  Switching over to that
     should be fairly easy.

  ** makeztxt has options.  Try "makeztxt --help".  Also, makeztxt can take
     regular expressions as options to auto-generate bookmarks for you.

  ** Need to be able to beam zTXT databases to other Palms... eventually...
