
README for makeztxt version 1.40beta

by John Gruenenfelder (johng@as.arizona.edu)
Saturday, February 10, 2001

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



What is makeztxt?
------------------------------
makeztxt is a simple commandline program that takes a plain ASCII text file
and compresses it into a zTXT database. makeztxt will remove newline
characters at the end of lines that contain text so that the paragraphs flow
better on the Palm screen.



Features
------------------------------
  * Creates zTXT databases
  * Use regular expression to automatically generate bookmarks
  * Includes libztxt, a small C library, so you can easily add zTXT creation
      to your program
  * Create zTXTs that allow on-demand decompression, or get 10% - 15% more
      compression with the original style zTXT.
  * Read regular expressions from a config file



Using makeztxt
------------------------------
The best feature of makeztxt 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.

A full listing of all of the options to makeztxt can be found on the website:
http://gutenpalm.sourceforge.net
For a quick reference, try 'makeztxt --help'

You can also put a list of regular expressions, one per line, in a file called
".gutenpalmrc".  This file goes in your home directory, or in the current
directory (if you have no home directory).  A sample .gutenpalmrc is included
with the distribution.

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
------------------------------
makeztxt uses zLib v1.1.3 (http://www.info-zip.org/pub/infozip/zlib).
You will 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.

You should look in the Makefile to make sure the program names and paths are
okay.  If you are running on Sun hardware, uncomment the line containing
-fpack-struct in the Makefile.  makeztxt will not work without this.  If you
are getting mysterious crashes, you might want to try this switch as well,
however, if you are on an x86 system, you should not enable that flag.

  "make"
You should now have 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...

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